wire-server
wire-server copied to clipboard
wireapp
Start moving internal documentation to /docs
Tasks
- [ ] start a wiki
- [ ] move some low-hanging fruit(s) from internal docs to it (cross-ref new location from old)
- [ ] figure out and document a way to dump wiki into a tree of
*.md-files in/docsin this repo. (my first idea, possibly no fun or invalid: write a small shell script that pulls everything from the wiki, overwrites the working copy with the changes, and commits this to a branchdocs-<timestamp>.) - [ ] (optional?) figure out a way to sync
/docsback into wiki, should somebody prefer to work there.
for a light-weight process to keep wiki and /docs in sync: we can add "call that script" to the release procedure.
So the wiki is the source of truth and /docs is effectively a read-only mirror? Or are changes from /docs going to be backported every release? On Jan 30 2019, at 10:22 am, fisx [email protected] wrote:
Tasks
start a wiki move some low-hanging fruit(s) from internal docs to it (cross-ref new location from old)
figure out and document a way to dump wiki into a tree of *.md-files in /docs in this repo. (my first idea, possibly no fun or invalid: write a small shell script that pulls everything from the wiki, overwrites the working copy with the changes, and commits this to a branch docs-
.) for a process to keep wiki and /docs in sync: we can add "call that script" to the release procedure.
— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub (https://github.com/wireapp/wire-server/issues/603), or mute the thread (https://github.com/notifications/unsubscribe-auth/ABc-apMD3oo3_O0LMAO8o1JTwyFgQ_GXks5vIWRggaJpZM4aZxxw).
good point @neongreen, i updated the description.
also, i'm not so confident this is the best task list for what we want to have.
feel free to suggest some simpler way of getting docs in place. i think the one thing that would be hard to attack is that we want a set of markdown files as user manual that can be used without getting near any source code.
Do we want the wiki to apply to develop, or to master (i.e. the latest release)?
If to master, then the proposed workflow doesn't work.
Generally, if we want to have API docs, I don't see what's the point of having a wiki at all as opposed to keeping a Github Pages site with docs rendered from /docs from master.
Alternatively, we can make it a part of the release checklist: somebody has to go through the CHANGELOG and update the wiki. In this case having /docs is pointless for me because I can just grep through the wiki repo instead, it doesn't matter whether it's inside the wire-server directory or not.
Generally, if we want to have API docs, I don't see what's the point of having a wiki at all as opposed to keeping a Github Pages site with docs rendered from /docs from master.
I agree with you.
Even though one point of having a wiki is that it has a different feel to edit it than a git branch in your own editor.
The reason for having /docs is that it can be aligned with the release nicely, and we do not loose documentation history (yes, I know, github wiki also has history, but I'm not sure it's as convenient).
feel free to suggest some simpler way of getting docs in place.
Alright, here's my own proposal:
A bunch of Markdown files on Github
We put docs as Markdown files in doc/ (which is, conveniently, a folder that we already have).
We also add a README.md there with a table of contents. Since Github can render Markdown, we get a documentation site for free just by linking to the folder.
Documentation aligned with release
We can give people a link to documentation for the previous release, for the current release, for bleeding edge, etc, because those are all links to folders in different commits.
Github can show rich diffs so if somebody wants to see how a specific page in our docs has changed between releases, they can kinda do it. Not sure it's very useful though.
Effortless wiki-like editing process
To accomplish effortless wiki-like editing process, people shall be allowed to push documentation-only commits directly into develop, similarly to how people can currently edit the wiki and nobody reviews their edits. For every file Github provides a convenient "edit this file" button, like on the wiki.
CI is set up not to run builds for such commits (or everyone has to learn to add [skip ci] in commit headings).
On the other hand, if we don't want anyone to be able to edit docs willy-nilly, then we won't have efforless wiki-like editing process anyway. A compromise could be "people edit everything willy-nilly and someone reviews the changes when doing a release". There are other compromises possible, too.
Linking to docs in code
Every heading gets a codename: ## SCIM and read-only profiles <!-- ReadOnlyProfiles -->. This way you can link to docs in code. Codenames are invisible during rendering.
The reason for having codenames (ReadOnlyProfiles) is that headings change but nobody wants to update code multiple times whenever headings change.
(Links to wiki have the same problem: either you have to create a number of small pages and never rename them, or if you have large pages and use anchor links, you can't really link to the wiki in code because stuff will break.)
Oh, right, the last point.
"that can be used without getting near any source code"
If we rename our doc folder to docs, we can get a Github Pages site for that folder by clicking exactly one button:
(NB: I might sound confident because it's 1am already and I'm tired. In reality I have literally no idea how to get good documentation for any project. None of the projects I worked on had good documentation, ever, regardless of whether I was responsible for it or not, so my hopes aren't high.)
I like @neongreen's last proposal: have a single place to keep docs relating to this codebase (in doc/ or docs/). CI already ignores changes to *.md files. (Keep in mind that some documentation relating to e.g. deployment, or unrelated to the wire-server codebase, should live elsewhere)
To accomplish effortless wiki-like editing process, people shall be allowed to push documentation-only commits directly into develop, similarly to how people can currently edit the wiki and nobody reviews their edits. [...]
On the other hand, if we don't want anyone to be able to edit docs willy-nilly, then we won't have efforless wiki-like editing process anyway. A compromise could be "people edit everything willy-nilly and someone reviews the changes when doing a release". There are other compromises possible, too.
Do you have an opinion on what should the compromise be?
I'm fine with small edits (typos, a sentence here and there) "willy-nilly" straight on develop without explicit PR + review.
The question is, when writing new sections (more than, say, 10-20 lines) of documentation, how "effortless" does it need to be, is a PR + review + merge too restricting for people to document things? Otherwise I'd prefer that - I assume reviews here to generally be quick and unproblematic. My assumption here is that the documentation about the wire server codebase doesn't change more than the code changes - many parts I expect to be very stable.
The question is, when writing new sections (more than, say, 10-20 lines) of documentation, how "effortless" does it need to be, is a PR + review + merge too restricting for people to document things?
There are unintended side-effects.
For instance, I often notice that I want to write something and then I feel like "someone will say that it's all obvious" and I'm not in a mood to fight over it so I'd rather not write anything at all.
Or someone will say "here, I thought of a better place to put this doc", or think of phrasing improvements, or whatever, and then I'll have to touch a PR again and again. And while it's open I might also be hesitant to touch the same piece of docs in a different PR, because <merge conflicts> and even more time spent as the result.
It's all well-intentioned for sure, but if I can reasonably expect that I might have to touch a pull request three times before it gets merged, I'd also not write it at all simply because it's not worth it.
Finally, I think that without a certain level of sanity we'll end up with e.g. false statements in docs anyway. A one-sentence edit can quite easily turn out to be problematic.
Overall I'm not sure we will be able to get good docs without a) putting more effort into it than we can afford, or b) being more disciplined than we are. We can still try the PR approach, but it could be more efficient to have something like "for every docs folder there is an owner, and this owner has to check and approve the overall changes to those docs whenever a new prod release is made". This can be enforced by creating a CODEOWNERS file on Github and making master a protected branch.