Colors can be changed with the Doxyfile found in the develop branch. It’s essentially a no-work-into type of design, and all effort was put into the automation, so we do need some work on the visuals. Doxygen can easily take a CSS file, I’ll work on a repo just for the doxy styling.
As for github, it’s where our project is hosted, and github is just the url. Would you like more commands for switching branch’s via the git binary? I’m not sure what you mean there : D The directions would be just about the same if our host was bitbucket, I think, I’ll re-read the document and see if I can get at what could be better. Feel free to suggest a change with a PR as well.
Thanks, the info at the beginning of the site looks not so great to me as well. It’s pulled from the README.md file held on repo, and doxy interprets markdown a bit different than github does. As time goes on it would be nice to come up with a better looking file, but everything is all on Github, so forks and pushes are always welcome.
I’ll add a little section about how to start to change the look of that site via git and github.
Having documentation is nice but the Arduboy library has remained at V1.1 for well over 5 months, and now the display does not work properly with the latest Arduino IDE V1.6.10 release.
Why work on documentation when the library has essentially become “abandonware”?
I mean, some of us don’t use the git command line, and don’t actually have git installed on our computers.
Currently your only installation instructions consist of $ git clone https://github.com/Arduboy/Arduboy.git.
Which makes the assumption a person downloading/installing the library has git installed on their computers.
Whenever I grab a new vesion of the library, I do so by downloading the zip form straight from github, unpacking it and placing it in the correct location for Arduino Studio. I think some people (particularly the less experienced, the less technical or people who prefer GUIs to command line) might benefit from an alternative set of instructions telling them how to do it without having to use a command line interface.
Definitely recommend getting into source control, even if not Git.
I haven’t used The Tortoise plugin for Git but for other projects where I am required to use Windows I commonly use TortoiseSVN for Subversion or for TortoiseHg for Mercurial. Might be worth a shot if you want a GUI but don’t want to learn the command-line version of Git.
I presume that was supposed to be directed at me and not a general comment?
My point isn’t just about what I choose to do for simplicity, it’s that some of the less experienced users may not be happy with command line stuff and for many it would be daunting enough trying to learn how to program in the first place, without added technical stuff before they’ve even got the library working. I for one certainly couldn’t imagine myself using a command line tool when I was first learning to program. Heck, I probably still didn’t know what a command line tool was and had probably never seen one.
On a personal note though, I’m not working on a project big enough or with enough people to require any more source control than what the github website itself provides, the time spent installing and studying a different source control system would not in any way speed up my development process.
I can download current versions of code, I can add new commits with proper comments and I can request/merge PRs. Those are all the Source control tools I need.
I would totally learn some version control if you are programming a lot. Whether it’s mercurial or git or any other choice. When working with a project, or on a project that is maintained by a group “at large”, they will choose a way to manage the project that participants in the project will want to use in order to participate.
The Arduboy project uses the git binary, and the source is visible via github.There would be no other way to push a change to the Arduboy Library source if one wasn’t using Git, so one would need to learn git to work on the library.
However, for “users”, the guide needs an update. There should be a sub section about using the Arduino IDE instead of git or a zip.
Feature?: we could also write an ansible play to package the zips from git when there is a commit. This is something we can, and probably should do, and link these from the front page.
Please see the develop branch of the Github page for the “rolling-release” of the Library. That is where you will find the most up to date version of the Arduboy Library, where the development is happening.
A commit of the patch for the screen can go into the 1.1 release, and that is probably what we will do instead of iterating the version. See the related github commit for the discussion.
That’s great, but when is this “rolling-release” finally going deemed stable, and be merged to the stable branch and released and tagged so that the Arduino Library will pick it up, allowing “regular” users and developers to use it? What good is a development branch if the changes are never frozen at some point and made generally available?
And I have to ask (as I have previously elsewhere): If branch stable contains the latest stable release and branch develop contains new development, what it the master branch supposed to be used for?
Less experienced users should be using the latest official stable release and install it using the Arduino IDE’s Library Manager, as detailed in Step 2 of the Quick Start Guide.
For the record, [quote=“Pharap, post:2, topic:2035”]
I don’t like the colour or the assumption that everyone who uses github also uses git.
[/quote]
Function before form, when we have a chance to reskinning it with some CSS it will develop a similar purple type look and feel eventually. This has been a project @ekem has been working on for some time so I imagine it’s great for him to finally get feedback on it.
For the record, I hate command line git and @ekem loves it. I go to github and download the zip file, this makes @ekem and probably others kringe, but it’s reality so we have to deal with it. Just so we know where we stand, there will always be lots of options for users. This documentation is meant more for how shall I say it “experienced” type developers who would use something like this.
Our lesson plans and tutorials will be more for the beginner and not require you to use any command line tools.
We will be having an update soon that works with the new IDE. And yes things have slowed down on the development of the library, but it should be expected that it evolves to some kind of steady state after all necessary features are there and has been properly optimized. You’re welcome to push updates if you like we will continue to monitor it.
But frankly, you’re talking to me who is full well in the camp of “it works, good enough”. We want to give people as many paths and options they have. Obviously a library that doesn’t work with the latest IDE is a problem, and we will fix that, as we will fix other bugs as we discover them.
@Dreamer3 was leading heavy development of the library, and did a bulk of the work. We wouldn’t be anywhere near this far if it wasn’t for him and others who really wanted to see a quality library instead of a bunch of copy-paste code from other libraries.
I hope people don’t mind, but I decided to leave a general reply and simply quote who I’m referring to in turn since it seems like several people’s replies were of a similar nature.
That’s kind of the point, in 4-5 years I’ve never yet needed to do that, I’ve only ever worked on a team of 2-3 people, so I’m going to keep doing what works until the requirement for something different arises.
Actually I helped modify a pull request that was supposed to have been merged once (wihtout using git), but for some reason yyyc514 closed it and resubmitted it himself so it shows up as if he had done it himself rather than the two people who actually worked on it.
Either way I probably won’t be assisting with the Arduboy Library again. At the time I wasn’t particularly aiming to assist with the library anyway, my primary aim was to assist my friend.
Ah, now we’re getting back to the main point. I partly agree depending on what sort of information would be included/how the tutorial would be handled. Either way it sounds more user friendly than trying to convince potentially non technical people the command line is their friend.
Also sounds like a good idea. (Not that I know anything about ansible or how easy it would be, but the results at least sound handy).
So hang on a minute, are you saying that such information doesn’t belong with the documentation?
If yes, does the git command have any business being there, and if not, does that mean you’re proposing part of the contents of the quick start guide should be included with the documentation?
True, but I couldn’t find fault with the function, hence the [quote=“Pharap, post:2, topic:2035”]Otherwise good move.[/quote]
For the record, I don’t hate it, I just can’t justify using it since I don’t work on any projects of a large enough scale to require it, either in terms of code size or group size. Like you I just download a new copy of the latest branch in zip form and work with that.
I beg to differ on this point. I think many inexperienced users would also use the documentation, even if not straight away. I remember when I was first learning to program MSDN was easily my most visited site, later tying with StackOverflow.
On the other hand, if the documentation were only used by experienced users, I would have thought they’d already know how to get a copy of the source code, or at least would know/be able to figure out what git command to use to acquire it if they had git installed on their computer. The kind of people who wouldn’t know what command to use would be the ones who wouldn’t have git installed.
Well, I’ve got two people asking me to read and give feedback on two very different readme files here. I’m going to read and examine both and then make another reply (or possibly replies) with my thoughts (hopefully soonish). Chances are I’m going to advocate features of both rather than simply claiming one to be better though.
Firstly I’ll say this focuses more on @MLXXXp’s edit since it was more drastic (in both good and bad ways), but I will say before I begin that I think all of @ekem’s additions were beneficial, but it was less drastic, so it’s not really fair to compare the two edits as if they were competing/conflicting since they were taking very different approaches and aren’t entirely mutually exclusive. Also I appologise in advance for taking so long and for writing such a long and in depth analysis, but old habits die hard and I kept stopping to look at the comments on the pull request (which I may get involved in at some point).
I like the introduction of @MLXXXp’s version since it gets straight to the point of installation, which is what most new users reading the readme will want to find out. I also like the external links that were added as that will help users that stumble upon the project by accident or were directed there from elsewhere.
However, I don’t like how it only directs people to the quick start guide and does not include the advice about using the Sketch > Include Library method within the readme itself. I agree that some of the install information in the readme might have been more than necessary, but I don’t think all of it should have been removed, I think the bare minimum should have been kept and the link to the quickstart guide should be there as a sort of “if this was not enough”/“for a more in depth guide, please see here” type thing. Certainly I don’t think the information about the examples or running on the development board were needed, but I think the readme should contain enough to get the user up and running. This is what @ekem’s edit was aiming for and I think that was a good thing.
Side point, feel free to skip:
(I’d also like to point out that the introduction of the quickstart guide is heavily about codebender, which might be offputting to new users. Note that at time of writing only 1.7k people have clicked the codebender links, whereas 3.0k have clicked on the arduino studio download page. I think this on its own should be a good indicator of what kind of information deserves pride of place. It’s also to note that 1.0k clicked the link to the zip of the stable version, which is clearly said to be not required if the Sketch > Include Library > Manage Libraries method worked, indicating it’s a very reliable way of doing things)
The additional information regarding the develop branch not being stable or debugged is also quite a vital addition.
Since the @MLXXXp edit removes a large chunk of what was there before, a lot of minor typographical errors have been removed with it, but one glaring problem is still present (and I know people will groan at me for this one).
The grouping of ‘C/C++’ in the introduction.
Despite what people think, C is not a subset of C++, they only partly overlap. Instead of ranting about why this is important, I am going to direct anyone who disagrees to the wikipedia article on the matter. If you can get through the whole article and still feel the two are still ‘essentially compatible’ then I’ll gladly listen to your reasoning, but hopefully the examples in the article will be enough to prove that someone who has only ever had experience in C might feel that such a description is a bit of a lie. (If you’re feeling brave, there’s a much more in depth analysis available).
The only problem with this is that you have the same information in two different places. If the information changes, you have to remember to update it everywhere that it’s documented. This is one reason why README.md needed to be updated. The Quick Start Guide was up to date but nobody bothered to update README.md to match. By having README.md just refer to the guide, you often only have to change one document. And, making changes to README.md involves editing, committing changes, updating the version number, then tagging/releasing a new stable version of the library.
You can’t use link clicks as an indication. A good many of the clicks on the .zip file were made before the library had been submitted to Arduino and was made available via the Library Manager. Before that time, the .zip file was the best way available.
After the Library could be installed via the Library Manager, I updated the Quick Start Guide with the new instructions, but this didn’t reset the click count on the .zip file. I suspect that proportionately very few clicks have been made on the .zip since then.
Yes, I was contemplating changing this, but my goal at the time really wasn’t to question the accuracy of that kind of thing. I just left that part as is.
The simple solution would be to maintain a list of where it is documented, and keep that list to 3 items or less.
To be honest though, I struggle to see a situation where the Sketch > Include Library > Manage Libraries approach wouldn’t work.
If the readme were to be kept to linking to the quick start guide though, I think maybe the quick start guide should be reorganised. In particular codebender should be made less prominent as it’s less important than the installation information, as it is the installation information that most people will be coming for. Perhaps information regarding codebender should exist in a separate post and the quickstart guide merely link to it? After all, codebender is not required to install the Arduboy library or begin writing code for it. It would serve better as an after thought, being mentioned either as sample code, a place to share code, or both.
In which case the forum tracking the number of clicks on a link suddenly seems like a not very useful feature.
I’d still say that somewhat shows the Arduino Studio method works well enough to be considered the main method of installation, otherwise people would have been going back and trying the zip method instead.
I know, this wasn’t a criticism of it having not been removed, so much as making the point that it will still need to be removed at some point.
If you’ve seen any of my previous comments on this, you’ll know I’m not a fan of codebender. @bateske and @ekem are, or were. It was @ekem who added the codebender stuff to the guide.
If codbender were to get out of the dark ages and stay compatible with the current IDE, instead of being stuck at a 1.0.5 equivalent, I might have a different opinion. As it is, we have to maintain a separate version of the Arduboy library for them, and sketches written for it can’t make use of any of the new functions and features added to Arduino since 1.0.5
On this basis, my official opinion is going to be that while I think it would be nice to have the installation information in the readme, I would settle for separating the Codebender stuff from the quickstart guide and place it in a separate file (or remove it entirely, depending on the consensus as to whether Codebender is worthwhile), thus making the quickstart guide almost entirely about the installation of the library. I also think there are other things that could be done to make the quickstart guide more appealing, but I’m worried getting into that would drag this thread even further off piste.
I’d like to take this moment to reflect on the fact we’ve gone from a comment about not liking the colour or the assumption that everyone uses git to an in depth discussion about the content of the library’s readme file, and now we’re discussing the quickstart guide. Neither of which seem to be particularly related to the original topic. Maybe that’s ok though, I don’t really know.
I’m doing some updates with your suggestions in mind.