Using the forum to host documentation

forum
1

Continuing the discussion from Configuration options for core snap:

@anewman Alex, as you know I’ve been experimenting with different ways of producing documentation for snapd for some time now, because the documentation we expose so far is neither broad enough, nor deep enough, nor up-to-date enough. Please don’t take that personally, though. Indeed I consider that my own fault for not having managed to establish a process so far that works for the team and produces the desired outcome.

At the same time, what you see in that thread is us trying to solve that exact problem, so please bear with me. We have many eyes on this space, a very good conversation system to exchange ideas, cheap and opportunistic edits by anyone, track record for who changed what when, and a very good history overview. This is a great place for people to learn from and for us to evolve documentation.

This won’t replace snapcraft.io, since there’s definitely a place for more structured and professionally designed on-boarding information. That said, the content in that topic is a great fit to remain here, and I would recommend changing snapcraft.io itself to point here instead, for the reasons above.

3

Alex, as you know I’ve been experimenting with different ways of producing documentation for snapd for some time now, because the documentation we expose so far is neither broad enough, nor deep enough, nor up-to-date enough. Please don’t take that personally, though. Indeed I consider that my own fault for not having managed to establish a process so far that works for the team and produces the desired outcome.

@niemeyer I believe I understand the problem you’re trying to solve; you’re trying to create a living corpus of documentation that draws in knowledge from a community of users and developers both internal and external. That makes sense to me so I don’t want you to take my suggestion as a fundamental complaint about your documentation process being an open conversation with the community. And I think that issues with the documentation will require a significant amount of internal and external effort.

I would be happy to become part of that conversation and even throw resources at it if it means that we can start working on the problems that we all see with the documentation.

At the same time, what you see in that thread is us trying to solve that exact problem, so please bear with me. We have many eyes on this space, a very good conversation system to exchange ideas, cheap and opportunistic edits by anyone, track record for who changed what when, and a very good history overview. This is a great place for people to learn from and for us to evolve documentation.

I think that your forum makes sense as a plan to evolve and move ideas. I think what I’m most looking for is a fundamental willingness to explain what we’ve created to our users in a clear and coherent fashion. I think we need to create a boundary between providing information we have vetted and consider canonical (pun intended) and community context we provide for illustration.

This won’t replace snapcraft.io, since there’s definitely a place for more structured and professionally designed on-boarding information. That said, the content in that topic is a great fit to remain here, and I would recommend changing snapcraft.io itself to point here instead, for the reasons above.

I think trying to bridge that rift across services in a way that seeks to deduplicate the information is going to create a gap in the accessibility of the documentation to users. If we try to feed the community’s knowledge and lore back into the documentation, meanwhile, it can become a product that our partners can deliver to their users.

Since this is an organically growing community-driven product, I think I agree on the importance of using forums like this to feed the documentation, but I feel that there’s an issue if that leads us to want to delete user-facing documentation to create a single source of information. Perhaps you could consider augmenting the documentation to include a sort “see also” or “relevant community discussion” element that links to these sorts of threads and underlines our position as a community project with professional commercial polish. If we can develop a better process, then we shouldn’t face instances where product documentation contradicts community lore-- it should flow from “some information” to “more information and context” in the community.

I’m not trying to suggest that we put the cart before the horse in terms of productization, but I hope that we can find some sort of compromise where our community focus does not block or hinder our process of providing that extra polish for our users by requiring that information only exist in one place at any given time. As long as the flow of information is refined, I think it should be safe for it to be duplicated.

4

Alex, the problem you are trying to solve is indeed not the same I am trying to solve. So we’ll need to find a way to meet in the middle somewhere. My goal is to, as much as possible, provide in-depth, correct, pleasant to read documentation for snapd. We don’t have that today, anywhere, and this looks like an interesting seed:

There’s a good chance that we as a community (not Canonical) can take care of organically producing that sort of documentation about the several aspects of the project.

This, on the other hand, is something that we have a harder time directly contributing with today:

That’s structured and professionally written documentation that needs someone’s full time attention. It also takes much longer to land changes in it for that reason, and because the people professionally writing it are not engaged in the development process on a daily basis, it also lags behind very quickly and across the board, and it also suffers in terms of depth for similar reasons.

Rather than prescribing a solution for the latter problem, I’m interested in hearing your thoughts on it.

5

@niemeyer So, we’ve probably got an issue with how our documentation is structured if we have to view the editing of web-based documentation as a full-time job. I think that building the structure, style, editing, or even providing some additional content or illustrations on that documentation can be viewed as a full-time job but the actual technical content should come from developers directly with no need for it to be digested by a documenter. There are a lot of approaches to this sort of problem, but I believe we’ll need one that ultimately exists across as many repos as we work in because we’re a distributed company and we need a distributed process that makes the documentation more of a franchise than a centralized corpus-- something very thin and minimal.

I’d be happy to deliver a fully thought-out model for how something like this might work, but for now I’d like to sketch out a high-level set of criteria to illustrate what I’m saying.

If we can define a structure for the documentation that allows units of documentation to be regular and atomic (e.g. a tutorial page, a set of configuration options, a guide; all written in markdown with a regular directory structure) then the developer doesn’t have to worry about the indexing and flow of the documentation. They’re simply following a style guide and providing content that is consumed by a process that integrates it with a larger documentation tree. If these documentation pages can live in various code-bases, then the documentation process can become more of a collection and compilation process using potentially hand-edited indexes that draw the content together somewhat procedurally. The top-level documentation page is then effectively a multi-repo checkout that walks the repositories and aggregates their content.

Ideally, the documentation team should build out the content, style, or indexes for the overall tree of content in our products without blocking on the developers-- and the developers can expand the content of the documentation with no regard for the structure. This should allow us to then require that the addition of new code that changes the documentation requires a documentation change as a criteria to be merged-- and that a release of the product requires that we recompile the documentation, leading to documentation on the web that should match what’s in the code. So, developers provide content; documenters provide hierarchy and context.

We’ve put some thought into this with the way we’ve documented stacks because we wanted to reduce the barrier to entry on the documentation sufficiently that it would be simple to edit for developers and follow our existing development channels with no gatekeepers between the quality/delivery process in code and publishing on the web.

I think with some design, we can reduce the friction enough that documentation tasks can be palatable for developers, but it’s going to require some time and automation. I’m happy to put that effort forward and show you a more formal proposal for this.

6

That sounds great, Alex, and exactly what was being proposed when I suggested linking here instead of simply updating content elsewhere. What we have here is a repository of markdown pages published in the web. It’s trivial to pick these pages up and integrate them into a structure. Not only that, but it’s a real-time and multi-user collaborative platform, which preserves detailed history for the changes performed, and encourages healthy conversations around each specific topic.

I believe we solved that side of the problem for you. What’s the needed now is the shell around the core content pages, and some code that formats the markdown in any style you’d like.

7

That sounds great, Alex, and exactly what was being proposed when I suggested linking here instead of simply updating content elsewhere. What we have here is a repository of markdown pages published in the web. It’s trivial to pick these pages up and integrate them into a structure. Not only that, but it’s a real-time and multi-user collaborative platform, which preserves detailed history for the changes performed, and encourages healthy conversations around each specific topic.

@niemeyer So how do you establish a relationship between the versioning of the code and this documentation? As a forum, this bears some resemblance to a github thread, but the process of change tracking and the connection with the code you’re referencing is entirely informal. Are you anticipating a perfect degree of discipline from the community or will your team effectively be curating these topics and creating an ad-hoc concept of pull requests by parsing replies and updating the top comment?

I believe we solved that side of the problem for you. What’s the needed now is the shell around the core content pages, and some code that formats the markdown in any style you’d like.

I think what you’re describing sounds elegant in theory, but it represents a completely linear development path-- this forum has no concept of branching and requires us to recreate the concepts of review and merging manually, completely discarding git’s simple representation of text diffs and github’s pull requests. I have no doubt that this can be parsed and snarfed into a document, but I don’t see the benefit of reinventing the concept of contribution of text content to a product in the form of a separate and incompatible system of change tracking through informal conversation.

I think there would be a lot of benefit from parsing some of these topics as seeds for documentation, but having them continue to exist as source seems like an awkward stretch of the process without removing any of the complexity in designing a documentation structure or process to parse the content. Shouldn’t we anticipate that git and markdown are more widely understood as a process of contribution?

8

So far I’ve only seen one proper way of doing this for rapidly evolving software: documentation needs to be explicitly tagged to inform the reader about when the stated facts started being true. Without that we end up with a body of information which will work or not arbitrarily, depending on which version is running locally, which is not so useful and very frustrating. Doing that requires some discipline indeed.

Quite the opposite: ideally we won’t have to branch or merge documentation, manually or otherwise, but rather just click on the edit button, fix/improve it, and save. If you want to see a nice diff, or who changed it, or what was changed, just click on the pencil on the top-right corner.

For example, I can even see that while I’ve been responding to your post, you’ve been making changes to it.

image.png878×87 18.7 KB

This is markdown. Maybe with some additional syntax, but nothing extraordinary.

9

I certainly don’t disagree that for the reader of the documentation, information about versioning is important and must be stated explicitly. However, I was referring to the tight relationship that documentation embedded in a git repo would see as we look through the history of a codebase; changes to code and their associated changes to documentation would be clearly and coherently mapped. For a developer/contributor to the documentation, which version introduced which text or correction would also be very clear. This information could be useful if we wanted to track down issues of accuracy with the documentation-- or collect metrics. There is a massive ecosystem of tools that become available to us when we accept a widely used versioning system.

So, how do I edit your posts? If I see an error that I want to fix as a contributor, how do I represent that diff to you? If you accept my edit, do we care about the concept of attribution or blame? It seems that we’d need to do some legwork to make that history readable.

If I’m the parser, which post do I choose? I assume the answer is the top one, which is then edited by the owner of the thread. Should you leave the company, does someone then get access to your account and assume responsibility for this documentation block or do we discard the thread and start anew, effectively discarding the history?

And when all this is said and done, the ultimate convenience becomes the web-based editor and lack of a commit/push action for the content-- so, it’s more accessible to contribute to but more arduous to parse and accept contributions for the “owner”. And when it comes to accessibility, as a professionally maintained distribution, isn’t our main value the selectiveness and care we apply to the content that we brand and share? I would think we’d consider documentation to be similarly sensitive to code.

All these editing concerns aside, we’re still just talking about a single informal relationship between web documentation and the forum. If the documentation were bound to the source code, perhaps we might find instances in the future where there is value in snapd or any given snap consuming and formatting its own internal documentation for a user (to be viewed on CLI or something). So, I think there’s some future flexibility to consider here as well.

We’re effectively describing the same distributed documentation system indexed centrally and open for user contribution. What do you see as the problem with using git/github for contribution as opposed to a forum?

10

That’s not realistic for multiple reasons. The obvious one is that features that most benefit from documentation regularly take dozens of branches to be accomplished, consisting of very abstract work that doesn’t map properly into a coherent high-level story. This “tight relationship” just doesn’t exist.

Interesting documentation pages should be wikis so they may be edited directly by anyone with a minimum trust level. We just need to make sure that the terms of service make clear that such edits are offered under a license that allows the documentation to be properly distributed as such.

My own main value relates to open source software. I was hoping yours was about documentation. :wink:

This is what the whole thread above responds. That’s the model in place for years, since the project started, and it has put us where we are today. We’ll find bumps along the way, but I’m willing to try something different and see what happens… I have a good feeling about this one.

11

In some development cultures, code follows documentation and specification. So you can say that you don’t see value in that relationship but it’s a bit overzealous to suggest it doesn’t exist. Relationships between concept and implementation can exist wherever we choose to build them.

So how does the forum provide that, then? It doesn’t seem like a great wiki either. I see that it’s a site for versioned text and discussion, but I’m not seeing how it becomes a collaborative document.

I think we’ve clearly got issues with process and procedure with regard to documentation and not tooling. If we treat it as an afterthought, it doesn’t matter how quick and easy the tools are-- it’s always going to look like an afterthought. It should be clear that the core content of the documentation needs to come from the same actors as the code and ideas and community content should be vetted by those same people. I don’t see how the forum improves upon that process; it merely creates a wider pipeline to get more unstructured content.

If I could make a suggestion: you seem to see a strict divide between our product documentation and documentation in the community. If we don’t have a solution for exporting the community content to the product documentation ready to go today, could we leave the professional documentation alone for now and leave it to other teams to get information from here to there? If it’s not a problem you believe in or agree with, then you can at least agree not to obstruct it. If it’s incomplete, it’s better that there’s formatted content than a simple link.

If we want to establish some sort of scraping process, then that definitely needs to come before content is deleted. There needs to be some curation allowed in the process somewhere and if that needs to be manual for now, then that’s better than nothing.

12

We write specifications before we implement code for non-trivial changes, and that’s not the same as writing proper documentation – far from it. Then, as I explained code changes are broken down across several independent PRs which bear little resemblance to a high-level story. So indeed that tight commit-level relationship you suggest between code and documentation doesn’t exist today, and there’s nothing wrong with that.

No, I see a tight divide between what we have today and what is needed, and I’m willing to try different ways to fix that.

I explicitly said in our previous call about the topic that you should feel free to experiment with different ways to solve these issues.

That said, you may hear again from me if we don’t fix them. For example, in our last call we discussed the fact the gadget snap format documentation was immediately out of date, because its content was copied out of the real specification and separated into multiple reworded pieces. Of course, on the next change we’ve made to the specification the documentation was already out of date, and meaningfully so.

Then, to this day our specification documents the prepare-device hook, which is important in the context of the gadget snap. Unfortunately, the reference in snapcraft.io not only cut that part out, but decided to put that inside “Configuration hooks”, which is completely unrelated.

So, quick recap: documentation broken apart, reworded, moved into the incorrect context, made hard to synchronize with new changes. It would be many many times better, for you, for us, for people using it, if that specification was simply picked up, synchronized and rendered.

Hopefully we understand each other now. We’ll be making an effort to have good documentation here, and would appreciate your help on that.

Thanks for the conversation.

13

I don’t think we’ve ever had such a call. For reference, I’m trying to solve this problem from the engineering side where the problem is and where the solution will need to come from. My team has come up with a good kernel of a solution that should help engineers to take a more direct role in technical content with less overhead and I’d be happy to share it with you if you’d like to have that call in the future. As it stands, we’re simply not responsible for the issues you’ve mentioned-- but like you, we’d really like to see them resolved.

14

My apologies. I’ve had a call with the team that was directly responsible for snapcraft.io, and we discussed the exact issue brought up above. I incorrectly assumed you were part of that team and either attended that call or was made aware of the conversation.

That said, the above conversation covers the exact details much better than I might in that call nevertheless, so please ignore my comments related to the call.

Glad we’re on the same page now, and want to see those problems solved.

15

@niemeyer, thanks for creating this topic. I haven’t replied on the previous topic yet as it raises all the points discussed above.

For clarity, let me lay out the snap* related doc stacks as they are today.

The documentation is splitted in five places: snapcraft.io/docs for an audience of snap builders, docs.ubuntu.com/core for board builders and brand store owners, dev.ubuntu.com/core for a general getting started with flashing core on your board, tutorials.ubuntu.com for a different step by step approach that caters to users who prefer more hand holding and the snapd wiki for direct developers updates.

  • snapcraft.io/docs is sourced from three places: a GitHub repo with the general structure and most of the content, snapcraft source code for plugins, the snapd wiki for interfaces. Note that wiki syncs only happen when a snapd release lands in the stable channel.
  • docs.ubuntu.com/core has much more: a GitHub repo for the same purpose as above, the wiki and a growing set of git branches on Launchpad for documentation coming from individual snaps part of Ubuntu Stacks. Same as above for syncs.
  • dev.ubuntu.com/core is sourced from a dedicated repo with on-boarding content
  • tutorials.ubuntu.com is sourced from individual Google Docs with a specific formatting

Having multiple places has its pros and cons.

On the pros side:

  • we can easily define a branding (for example: cross-distro VS Ubuntu Core as the only OS) and an angle around each documentation stack
  • we can cater with more granularity to different types of audiences, as not everyone is making a board for example
  • we can define tailored, progressive journeys and choose to only expose things that are relevant to your current task. An example of this is people coming from the RaspberryPi site: they land on steps for their specific board, and are ramped up to 1) flashing and using Ubuntu Core 2) Installing relevant snaps for developers 3) then depending on their interest, we orient them to making a stack for their project or to making and testing snaps.

On the cons side:

  • it is confusing for contributors and contribution steps are not clearly laid out on each site
  • the search facilities and general functionalities can vary between sites
  • keeping everything up to date can be a challenge, especially if the source of the documentation is free form and needs manual changes (whether it is small formatting tweaks or more structural ones) to adhere to the quality and layout of the rest of the stack
  • where does “piece of content” go? If we take the example of core configs: it’s a clear contender for the board makers stack but it’s also a very useful example of what you can do for your own snap

Now, a quick overview of things that are in progress:

  • Revamping developer.ubuntu.com to act as a developer hub between all Ubuntu upstreamed projects
  • Restructuring snapcraft.io/docs, in depth, which is a group effort in which Snapcraft Docs Days play a big part (our first one was last friday as you know and I’m happy to say it was a success in terms of contributions)
  • Updating snapcraft.io/docs to use documentation-builder which is our tool to build docs.ubuntu.com
  • Bringing versioning to docs.ubuntu.com/core
  • Changing tutorials.ubuntu.com to handle Markdown sources
  • Adding to each page generated by documentation-builder a link to its markdown source

Going further, I do agree that we can reduce the cons, by sourcing a lot of the documentation effort in an easy-to-edit place that is looked at daily by upstream developers and wider contributors. But I think that we need guidelines (formatting ones) for these to happen and answer a few questions:

  • Do we want imports or redirects to the forum? Maybe we can do both, by importing on stable releases (or candidate?) and dynamically adding a note on the page that the living documentation for the next release is on the forum at “this” page.
  • Do we want to maintain a map of doc pages in the forum? Could it be as simple as adding a tag to the relevant threads? EDIT: Just seen the current “doc” tag.
  • How do we version the documentation? I’m assuming a comment in the markdown in an easy to parse format, but can Discourse provide links to raw markdown from an older edit?
1 Like
16

Thank you very much for the update, @davidcalle. Great to see so many good things coming into our documentation process.

Answering your questions:

I think we don’t need to pick one or the other here. If we’re able to do both, we can easily choose what’s the most appropriate option on a case-by-case basis. Content that is already pretty formal and static might get imported, while content that is more dynamic or more conversational may be linked to so it’s observed within the context of the forum. Often the conversation below the top post will serve as insight into the topic, and the ultimate goal of the documentation is really for the reader to learn, so the interests are aligned even if it feels less formal.

Yes, something like a tag would probably be a good idea. We have a doc category mainly for discussions related to the documentation, like this one. Actual documentation will more often be categorized under what is being documented (snapd, snapcraft, etc).

Let’s wait a bit until we have a few topics flowing through that system to see what metadata will be useful and we can then try a few different things and see what works best.

The answer to this question depends on the goal. The base approach recommended is picking up the latest version at all times when importing, after all part of the goal is precisely ensuring people have access to up-to-date information. The revisioning to ensure correctness should be done here instead of outside.