Updated: Comment #59
Please review items #5 and following in the Proposed Resolution, because it will change how we do the developer tutorial documentation, quite radically. Unless good arguments are brought against it, we'll probably adopt it soon, so speak up now if you care. Please.
The top-level page on https://api.drupal.org/api/drupal/8 is one of the primary entry points for new developers into Drupal 8, but its list of topics is woefully short and doesn't contain any of the new concepts in Drupal 8. That can be found at http://drupalcode.org/project/documentation.git/blob/refs/heads/8.x-1.x:....
That links to certain select things under "Topics" (https://api.drupal.org/api/drupal/groups/8) which are effectively the @defgroups in core, but these are also missing key new concepts such as "Plugins," "Services," likely many others. These are important though, because they're directly related to the discoverability of these things.
It would also be good if all of the developer documentation was centralized on api.drupal.org, because although https://drupal.org/developing/api exists, many people don't know about it.
Anywho, this is a meta issue to sort this out.
Note: Items 1-3 are relatively straightforward and need to be done.
Items 5 on are a new idea and they need review.
- New api.d.o D8 landing: Identify (Done - see comment #6) -- Identify an outline for the Drupal 8 api.drupal.org landing page.
- New api.d.o D8 landing: patch (Not started) -- Take this outline and make a patch so that it becomes the Drupal 8 api.drupal.org landing page. Issue has been filed:
- New api.d.o D8 landing targets: patch (Not started) -- We can then get people going on fleshing out each of the landing topics, which will be core patches.
- developing/api tutorials - write (well underway) -- Everyone can continue working on the API tutorial docs on d.o for now under https://drupal.org/developing/api
- current developing/api tutorials - new home - proof of concept (Done! http://docs-api.redesign.devdrupal.org/d8book ) The idea is to get the documentation currently on developing/api for Drupal 8 onto api.drupal.org, so that people will find it and know about it more easily, and so that all developer-related docs would be on the same site. We could do this in two ways:
Method Details Pros Cons Nodes
- Move the nodes from developing/api to api.drupal.org
- Open up api.drupal.org so that people can edit nodes there
We're used to this way of editing. Everyone can edit, so it's easy to contribute. It's fairly uncontrolled - leads to spaghetti documentation. You have to edit in HTML on the browser (HTML is not the best format for writing in). Also, right now there are no nodes on api.drupal.org or permissions for themm and not many people actually have accounts there (only if you have commented, which is 90% spammers anyway). And version (D7, D8, ...) is not obvious -- do you fork or modify docs when a new version comes out? Markdown/Git
- Make a Git repo with text/Markdown syntax files containing the docs
- Display them on api.drupal.org as pages
- This is workable/working on a test site, see below
Markdown is (arguably?) easier to write than HTML. You can use a text editor to edit. Developers like and know how to use Git and text editors. We can make the output into PDF and other formats as well very easily. (!!) When it's time to go to the next Drupal version, it's easy to branch the docs as a starting point. We're not used to AsciiDoc or editing docs this way (except of course that API docs are already in the code base). We would have to make the Git repo discoverable (with a block explaining where the pages are coming from?), or possibly editable on-line with a tool that automatically makes a fork/pull request or a patch. Edits do not go live immediately. Editing process (edit, make a patch, file an issue) is a bit more tedious than with Drupal nodes, even if the creation of the patch can be done from the Edit page right on the site.
We thought maybe the Markdown/Git/Import method would be better. So, jhodgdon did the following to test out that method (see comments #11-13 for more discussion):
- Made a preliminary set of documents taken from the API tutorial docs on d.o, and it put into AsciiDoc into a sandbox repo: https://drupal.org/sandbox/jhodgdon/2127335
- Figured out how to compile AsciiDoc into HTML and PDF and display both on api.drupal.org. The (sandbox) module for this is: https://drupal.org/sandbox/jhodgdon/2127337 Note that we could also create other formats from the same source if we wanted to (.mobi, etc.).
- Deploy it on a test site: http://docs-api.redesign.devdrupal.org/d8book
- former developing/api tutorials - convert (a few are started) -- We will need to convert the d.o files in https://drupal.org/developing/api into AsciiDoc and commit them to a repo (marking each page at the top with a note saying not to edit any more outside of the docs repo). And we will also need to make both sandboxes into real projects. And give more people commit privs to the docs repo. We will need to figure out who should be maintainers of the docs repo (unless we want to put it into Core?). The concept would probably be to think of the docs maintainers as "documentation editors", and people would most likely self-select and request maintainership if they think of themselves in an "editor" role.
- former developing/api tutorials - deploy (not started) -- At some point, when a critical mass of conversions has been done, we need to put the new module on api.drupal.org and set up Jenkins jobs to update the docs from git, and run the scripts. That is probably an hour of work for someone like @drumm. The scripts require that 3 Linux packages be installed on the server where api.drupal.org is living, but are otherwise straightforward to run and quick. Details are in the project README.
- Live git editing on the web (proof of concept working) -- We need an "Edit" button somehow, so that people who find problems or want to add to the pages can edit them easily. This would need to leverage some existing technology to find the Git source, allow you to edit it, and post the result as a patch or pull request, and thereby allow people who aren't Git gurus or who don't want to figure out where the Git repo is to propose edits to the documentation. Technology that could be used:
- GitHub: Github generally allows people to edit files in the web interface via a browser. If they don't have commit access to the file it says "Clicking this button will automatically fork this project so you can edit the file". Then, submitting a change to this file will write it to a new branch in your fork so you can send a pull request. [Symfony uses this]
- GitLab: http://www.gitlab.com/ - has a web editor (and forking, pull requests, and a web UI for merging).
- Prose.io (built by former Drupal shop Dev Seed for use on Jekyll/GitHub) is one option.
- PHP.net itself has some tool we could look into borrowing.
- Home-grown Drupal-based solution (this is what was used)
There are some comments below where these possibilities were investigated and the home-grown solution was chosen.
a) Take care of items 2 and 3 in the Proposed Resolution.
b) Decide whether we want the AsciiDoc approach presented here for the developing/api tutorials.
c) If we do go with the AsciiDoc approach, decide whether it should go into the Drupal Core repo or a separate repo, and if it's a separate repo, decide on a framework for designating maintainers.
d) If we do want to use the AsciiDoc approach, convert the existing documentation to AsciiDoc and deploy on api.drupal.org, along with the technology to display and edit the resulting docs. There are several UI issues that need to be resolved if we do this:
- Theming - the current Proof of Concept site has a toolbar that isn't like other stuff we see in Bluecheese, and the editor window is too wide.
- URL - we need to pick a good URL scheme for these docs. Maybe something like /reference/8.0/xxxx.html ?
- Navigation - make sure people know that these docs exist when on api.drupal.org.
- Make ability to edit more obvious - make a big Edit button somewhere (the current links are too subtle), make sure the procedure for what to do when you've downloaded the patch is more obvious, better text around "file an issue" links and maybe a big File an Issue link near the big Edit button?
- Make the Preview button more obvious in the toolbar.
- Make it more obvious that AsciiDoc is being used and a more prominent link to the AsciiDoc user guide
- Make the Return to Book link take you back to the page you were on
- Make sure the editor is accessible.
User interface changes
More relevant topics list on api.drupal.org, and new developer documentation book on api.drupal.org. Editing developer doc book via patches, a Git repo, and AsciiDoc markup (with on-line editing capability) instead of Drupal nodes and HTML markup.