We have 2 example features that show up in the 'experimental' features list, as well as an index.php for the front page of api.aegirproject.org.
I'd like to move these to their own project. This would allow us to add additional example modules without cluttering up our features list. We can then invite newer contributors to co-maintain, as a way of on-boarding new developers. I'd also like to move developer documentation from the community site to the api site, by including it in this new project, alongside, and linked from index.html.
DEMO: https://aegir.readthedocs.org (redirected from http://docs.aegirproject.org)
docs repo: https://github.com/aegir-project/documentation
Comments
Comment #1
helmo commentedI like the idea of having more documentation in/with the code. It would allow a single commit to change both documentation and implementation. Moving it to a separate d.o project would conflict with that.
It also adds the need for yet another release node to be created in our release process.
We could create a group 'examples' instead of placing the examples under experimental.
Comment #2
helmo commentedYou we're thinking about a 'hosting_examples' project? would you want that to be included in the makefile?
Comment #3
ergonlogicAnother option is Read The Docs, a VCS-based documentation generator that uses my personal favourite markup reStructuredText. With that, we could move the user docs into git, hosted on github or bitbucket, and allow pull requests to edit.
As much as I like (re-)building wikis over and over in Drupal, I think this'd be an excellent way to manage our docs, while off-loading all the infrastructure burden.
Comment #4
helmo commentedRead The Docs seems the way to go ...
How would we keep Aegir major version specific docs apart? The little 'v: latest ' thingie is not very clear.
And after releasing Aegir 3 the 'latest' would move on to be updated for ongoing 4.x work. Can we default to the current stable?
Comment #5
helmo commentedComment #6
helmo commentedI've just converted one more page to http://docs.aegirproject.org/en/latest/install/debian.html
And linked it from http://community.aegirproject.org/3.0-beta1
It's good that I read through it all, as I removed much outdated stuff, but some automated conversion would be nice....
Comment #7
helmo commentedThe html2rest tools saves a bit of time here ... https://pypi.python.org/pypi/html2rest
One vim replace patterns I used more then once: s/`/``/g
Comment #8
ergonlogicSo, also for use on readthedocs.org, I started using mkdocs to generate http://docs.getvalkyrie.com (https://github.com/getvalkyrie/valkyrie-docs, also still very sparse). It uses Markdown rather than ReST, and seems quite a bit easier to use overall. Before we go much further, we should consider whether this'd make contributing to documentation easier for less technical folks.
Comment #9
ergonlogicSince our current wiki is based on markdown, conversion should be easier.
Comment #10
helmo commentedYes please... I do prefer markdown.
Comment #11
ergonlogicI've converted the docs project to use markdown. I also wrote up a pretty detailed README in the project root, and cleaned up the existing docs somewhat.
Comment #12
ergonlogicOne note-worthy limitation of mkdocs is a lack of support for deeper tree: https://github.com/mkdocs/mkdocs/issues/6. I'm working on a fix for this, as time permits. We'll probably need to self-host for awhile once this is fixed, if readthedocs.org doesn't adopt it quickly.
Comment #13
themusician commentedI started a branch for the hooking into Aegir documentation. https://github.com/theMusician/documentation/tree/hooking-into-aegir
I'll add examples that I have as well in the areas that are sparse such as http://community.aegirproject.org/content/injecting-drushrcphp.
I hope to have a pull request made by the end of the weekend.
Comment #14
themusician commentedThe community Aegir docs have a lot of general good idea pages such as [DNS wildcard Configuration](http://community.aegirproject.org/dnswildcard). There is nothing specific to Aegir within that page. When I first stumbled upon Aegir, in the .4 days, these general pages were of help.
As the project matures, it seems like a lot of this documentation should be moved to a different resource than the Aegir 3 manual. The manual would instruct how to use Aegir in the vanilla format of a fresh install, and then these other resources could help individuals do more with the system.
The following pages within the [post-install section](http://community.aegirproject.org/content/administrator/post-install-con...) would move into this new resource area.
* [Setting Up Varnish & Memcache with Aegir](http://community.aegirproject.org/node/388)
* [Using a proxy cache to accelerate platform builds](http://community.aegirproject.org/handbook/administrator/post-install-co...)
* [DNS wildcard Configuration](http://community.aegirproject.org/dnswildcard)
These two pages seem a bit superfluous and serve more as general tips on being a systems-administrator. Again, that is not bad, just perhaps not appropriate for a concise Aegir manual
* [Working as aegir user](http://community.aegirproject.org/node/427)
* [Create a SUDO user for server administration](http://community.aegirproject.org/content/content/administrator/post-ins...)
Any objections to creating an area in the new manual for this legacy content that is not strictly Aegir 3 content? I would propose we name the section "Legacy" and shuttle that content there.
Comment #15
helmo commented+1 on keeping the manual focused on Aegir and delegating general sysadmin advise to the rest of the world.
I suggest to leave the 'Legacy' content where it is now and archive the whole book structure some day. Maybe we could use https://www.drupal.org/project/print to archive it and commit that to the docs repo.
Comment #16
helmo commented@cweagans created an archive which is now served on: http://community-archive.aegirproject.org
Comment #17
ergonlogicIf we spin off the example features, we can re-include them via our dev makefile.