[META] Track 3: Drupal Starshot documentation

Hi @pameeela and all, I am happy to work closely with the Drupal Association to ensure the success of this track. Training and documentation are the launching pads of achievement and enablement, and they were my active specialities as a Drupal curriculum manager at Acquia for nearly eight years.

Hey all, I would love to help support this track as well! I presented on technical documentation during DrupalCon 2022 and have years of experience with technical writing along with teaching in higher education at the US Collegiate level. Currently I support Drupal core with documentation on SDC along with a custom starterkit theme called Prototype. I also have experience reviewing existing documentation and testing user workflows and tutorials.

Is there going to be a discussion about what documentation format will the Drupal CMS use, or has that been already decided as we a have a POC in #3473439: Create a few POC pages for a future Drupal CMS Guide → ?

I don't think the choice of format is finalized, but the decision would lie with the track leads (Amber Hines Matz and eojthebrave, IIRC).

@poker10, that's a great question.

There's no final decision about format that I'm aware of at this point. Right now Lenny is the track lead for the documentation track. Amber and I helped created the POC work linked above as part of having something to show in the demos at DrupalCon. But I don't know of any plans beyond that initial POC.

If you've got suggestions for format I would certainly love to hear them. And I suspect others would as well. The formatting for the current POC work was totally me basing things off what we had previously done with the Drupal User Guide and I'm not personally tied to it.

If you've got suggestions for format I would certainly love to hear them.

Thanks for the information! I did not had a specific suggestion regarding the format in mind, but wanted to add my 2 cents.

The documentation POC looks indeed good. What I am curious about is, if there is a way how to connect it to the Drupal.org search or make the documentation available to search engines? The files/wiki pages in Gitlab seems not indexed, or are at very low positions currently - just try to search something from https://git.drupalcode.org/project/drupal_cms/-/wikis/Contributing-to-Dr... . This is causing a big issue, because potential contributors and other people simply cannot find this wiki (except going there with the link from the drupal_cms project page). I have this information from several contributors, which were unable to find this contribution wiki using Google. On the other hand, if you create a simple documentation page on drupal.org, it is very well indexed and available.

Other point to consider is, that if the documentation will be in the git repository, there will be a restricted access to it, with limited possibilites to make changes. We experienced something similar with D7 form api page (https://api.drupal.org/api/drupal/external_documentation%21developer%21t...), where a lot of bugs was in different issues and these issues were here unfixed for a long time (I am not blaming anyone for this!). If that documentation was available to edit as a standard documentation on d.o., it would have been fixed a long time ago. This is probably not an ideal example, because of the specific formatting, but the point is the same - we will restrict possible updates to a process with issue / MR / approval / commit. It has also potential to overhelm committers and track leads in the first phases, because I suppose there will be a lot of changes in these docs files. It can also discourage some contributors wanting to add a quick fixes or quick additions, because the need to create an issue, MR and so on.

So I think we should consider whether the approach with a git based documentation will work for us.