Go Down

Topic: Reference page no longer references AVR library functions. (Read 1 time) previous topic - next topic

aarg

Is the link to the AVR library really nowhere to be found on the updated reference page? If so, why?
http://www.nongnu.org/avr-libc/user-manual/modules.html
  ... with a transistor and a large sum of money to spend ...
Please don't PM me with technical questions. Post them in the forum.

cattledog

Something definitely changed with the reference page. I was checking the attachInterrupt() reference for something, and I noticed that all the recent material about the syntax attachInterrupt(digitalPintoInterrupt(), isr,mode) has disappeared.

pert

I'm not sure what the reasoning was for changing the content but the cause of the general change is actually really cool. The language reference pages content is now generated from a GitHub repository so it's super easy to propose changes and easy for the Arduino team to merge those changes and push them to the website. They even have an "Edit" link on every page now.

Here's the repository: https://github.com/arduino/reference-en

So you are welcome to submit a pull request for adding that content back in. It looks like you can still access the old content by modifying the URL a little. For example, the new attachInterrupt() URL is:
https://www.arduino.cc/reference/en/language/functions/external-interrupts/attachinterrupt/
The old URL is:
https://www.arduino.cc/en/Reference/AttachInterrupt/
Note the change in case.
I don't know how to access the old reference home page.

I suspect there will also be some regressions of recent improvements made to the old reference pages because they started on this new reference system years ago with the reference content at that time but then lagged super hard on the project until a few months ago when they started working actively on it, but without redoing the scrape first.

They're also using the same system for translating the reference to other languages:
https://github.com/arduino?q=reference

Supposedly the plan is to do the same with the library reference pages but that content will be stored in each library's repository.

pert

It looks like there is progress towards fixing the attachInterrupt issue:
https://github.com/arduino/reference-en/pull/196
Pretty quick action from the Arduino team!

Previously you had to submit issue reports to the IDE repository, which was a bit off topic, and if an issue didn't get dealt with quickly it got buried under dozens of other issue reports. So I'm really glad to see an improved system that makes it easier to submit proposals for improvements and is less time consuming for the Arduino team to implement those changes. Unfortunately there is still a lot of website content that we have to use the old system for. It used to be that I would report an issue and it would be resolved within a few days but I have a lot of issues in the tracker that have been sitting for months now without any attention so I have not been very motivated to add new ones. I guess I'll focus mainly on the language reference pages and hope they will get the library documentation system going soon.

cattledog

Yes, I submitted the issue and did notice the quick response. I also reference your comment that some other reference pages may have reverted to previous versions. I hope that the admins will be proactive in bringing other topics up to date. Thanks for your advice on submitting the issue to GitHub.

lcipriani

Hi Arduino Users,

Let me give you some more info on what we did and are going to do next. We know our website is not the best possible (actually has a lot of issue, main one is not really readable on mobile) and is not really a CMS, this is preventing us to quickly improve it.

What we did:
We finally were able to move from a pure wiki format to a more modern static generator website so the new reference pages are much faster then the rest of the site, using a CDN and they work on mobile!

What is going to happen:
Because this side project experiment (the new reference) worked quite well we are going to move our whole website to a similar architecture (some internal editors and a static content generator). It will take almost 1 year from now but that's our long term plan.

In addition to all of this we are going to have a serious search engine on our websites. Again this is a very long project but will change our lives.

And thank you everyone for your great contribution to the reference!

pert

Thanks for the update lcipriani.

Is the plan to eventually make all of the website content editable by the same sort of system as the Language Reference? I know this is planned for the library reference pages, but I'm asking about the rest of the content. That would be great. I'm really enjoying being able to submit pull requests to the reference-en repository. The old system of submitting issue reports was very inefficient both for me and the person on the Arduino team implementing the suggested changes.

I'm also glad to hear about the search engine. Just yesterday I spent a lot of time with a Google search for an old thread. I knew the exact keywords that existed in a reply I had made but it didn't show up in the results. I ended up just scrolling back through tons of my replies to find it.

mastrolinux

Hi @pert,

No we do not think allowing editing of the whole website is something useful for both the Arduino Company and Community but we want to open as many places as possible if it makes sense to have contribution from the community. If you have any suggestion about what are the most relevant sections in your opinion to be opened then let me know and we will evaluate.

The search engine will roll out next week on the blog as first as a test then if users will like it we will extend to all our websites one by one.


pert

I'd say just make as much of the content editable via pull request as is feasible, starting with the pages leading from the Learning tab. Now that you have the Language Reference system in place it should be quite easy to extend that to the rest of the documentation content.

It may take some work to set this up but I think it will very much be worthwhile in the long run. The thing is there is a lot of room for improvement in the documentation and good documentation is so important for the target Arduino user. I can find issues on almost every single page. I understand, it's a lot of content and typos happen but it doesn't need to stay that way. The Arduino community is a huge resource but you need to efficiently tap into that resource. A lot of people will not act on issues they spot in the documentation unless you make it easy for them. There have been bad feelings in the community related to long-standing issues with the documentation. When they report these issues on the forum (as they are told to do), nothing happens because nobody with the power to make the edits bothers to read the forum. In fact the link even takes them to the wrong forum section (https://github.com/arduino/Arduino/issues/6526)! Making effective use of the community is even more important now that the documentation translation project is under way. The new Language Reference with the Edit button is such a huge improvement and shows great vision. I really think the system can serve as a model for other open source projects. Kudos to the people involved in making that happen!

I suppose the product pages might use a different system but they are also documentation and I have found quite a few typos and errors on those pages. I have submitted issue reports to the arduino/arduino repository for some of these but the latest (4 months ago) ones have not been acted on so I have felt that it's not worth my time to put more energy in that direction, even though I have a long list of additional issues I could report. I think part of the reason for that is they get buried in the arduino/Arduino issue tracker where they are not even really on topic. It's really inefficient for me to manually generate a diff for the edits and then for the Arduino team member to make those changes, rather than a pull request when I could directly edit the content and the repository maintainer could just review the changes and hit the Merge button. So here you have an example of a potential volunteer anxious to work for free but unable to do so. If it's not easy to extend the documentation editing system to the product pages I have an alternate suggestion: Move the bulk of the board documentation out of the product pages and into the standard documentation system, then just link to that content from the product pages. The product page would simply contain the sales pitch for the board and link to the board documentation page for the rest of the info. This would also be linked in to the Getting Started pages for each board.

After that, what remains of the website content is what I'd call infrastructure. Things like the home page, store pages, contact page, etc. Some of that content has issues also but my primary concern is with the documentation. We can continue to use the old inefficient system for the rest.

Go Up