Improving the documentation

I’ve mentioned previously that as a newbie to snapcraft the documentation leaves a great deal to be desired.

What makes it worse is that we now seem to have three places for doco.

https://docs.snapcraft.io
https://snapdocs.labix.org/
and to some extent the forums.

I know we all want the next latest features but I have to say for a project like snapcraft the most important feature is documentation.

Currently the project is seriously failing in this regard.

I’ve now been working on building a snap and its taken me a couple of weeks and I think it really should have only taken 2-3 days if the documentation was up to scratch.

We need a single documentation site and it needs to be coherent and complete (at least as far as possible).
Putting some resources into the documentation will greatly speed up the adaption of snapcraft.

So please this really needs to be your number one priority!

Regards,
Brett

5 Likes

I also have a feel that the documentation is lacking :
The location of the valid documentation of the snapd REST API / snapd deamon API? … so i want to know what is missing and how your guys would like to fix it.

I would nice if the documentation could be auto generated from some source - probably via annotated documentation / source code. Human generated documentation will always be lacking, so auto generated documentation is much preferable.

Regarding my question about the API.
I suggest using Open API (previous known as Swagger) to describe the API : https://swagger.io/specification/

@bsutton As I mentioned in our conversation two days ago, we are already working on a major refactoring of the documentation on that experimental site that you link to, precisely because we believe documentation is important and it’s currently lacking.

In those links you can find details about why we are doing this, and exactly how we are doing this, so if you are interested we’d love to have your closer participation on it. Please feel free to reply in that topic too.

About it being unclear which site is which, every single page on the new site has a banner hopefully making that very clear, and with a link to the current official site.

Despite the experimental label, in recent calls we’ve had there was some good level of agreement on it, and it all indicates that this is indeed the direction we’ll be moving towards. Even more if we have your help on that!

@LarsTH Code documentation is already generated from source code, but this is not code documentation but descriptive text, so we are using markdown here in the forum and automatically generating the web site at https://snapdocs.labix.org (for now, better URL later) with it.

About the documentation for the API, I have mentioned in the topic introducing the new documentation site a proposal for the API docs:

If you’re interested, we can try to port just one of those pages over, and then discuss the new format until we’re both happy, and then we can do all the other ones following similar guidelines.

What do you think?

I guess the premise of my post was to call for additional resources to be applied to getting the doc in a reasonable state and just complete the job of migrating to the new site.

My concern is that while it appears that a large chunk of resources have been applied to development, the documentation is seriously under resorced. This is clearly a major problem for the project as from first hand experinced it makes the cost of building snaps prohibitive.

I’m also concerned that there isn’t agreement on where the documentation is to be hosted.

Read this post and the comments from @popey.

Clean build - using LXC

From my perspective the experimental site it’s fine. The main criteria being that it is easy for the community to find and update the doco.

I think what we need right now is to:
Copy any content from the old site to the new site (even if it’s wrong).
Decommission the old doc site.
When responding to posts encourage the core team to update the doc and send a link to the doc rather than putting the answer directly in the post. From experinced with other projects this initially takes a bit more time but you quickly gain the time back as it reduces questions and improves the doc at a faster rate.

Have a resource spend some time to work out the structure on the documentation site and create an outline by creating placeholder chapter headings to give contributors some guidance where to place new content.
Have a resource that is tasked with overall responsibility for the documentation and has enough authority to ensure that core developers update the doco when they make changes.
The above steps will remove the current confusion,
Make the new doc site easy to find (as a newbie it was not easy to find).
Ensure the whole community is working in the same direction.

As an outsider I can see that snap potentially has a bright future but your single largest impediment to the community getting behind snap is the documentation.

Sorry if this comes off as a bit aggressive that’s not the intent.

Not aggressive at all. This is all very reasonable and you are right about every single point in your analysis.

The reaction from @popey in that topic is partly my fault, because I should have had a call with him and @wimpress a while ago to provide some more context about what is going on in that area, and how the plan is being organized. So I apologize for that.

Also, for context, this is a historical problem we’ve been trying to solve for some time, with a few different ideas tried, but nothing really worked as well as it needs to. And I’m not assigning the blame to anyone else here… we, the development team, ought to have done something ourselves for a long time, because it’s just not reasonable to expect someone outside the team to be able to catch up with the pace we walk.

Your document is great, thanks for putting it in place. I will do a pass there later just to tweak the formatting if you don’t mind. Feel free to do other documents too.

This is exactly one of the reasons why we’re doing that experiment the way it’s being done, as the forum as the hosting site for the underlying content. That, and this conversation right here… not only we’re easily and quickly collaborating on the new documentation, but we’re also discussing and improving our idea around it.

Win win.

Feel free to tweak away.

Thanks for answer, @niemeyer.

I am not interesting in contributing.

Rather I am interested in using documentation - in particular the API, with the purpose of creating GUI snap management software for the Terminal / shell challenged end user.

Regarding the GUI software: I am interested in an offline database with all information of all snap packages in existence, because:

  • An offline database is fast. An internet connection can be slow, which could result in an unacceptable response time.
  • It is easy to make a search in a database.

At the moment I am in the early analysis stage.

I didn’t find any snapd API documentation on https://snapdocs.labix.org/

On the wiki page of the snapd API where is a **Robert Ancell edited this page 14 hours ago · 101 revisions ** where 14 hours is relative to 26. feb 2018 00:48 UTC+1.

So @niemeyer is it safe to assume that the API description on the Wiki is the current one?

Yeah, and it’s quite up to date. I just want to move it over and refactor it a bit in terms if style and also break it into multiple pages which are easier to digest.

But don’t worry about it. When I’m done with that I will replace that page with a note pointing to the new location