Problem/Motivation

To execute the Proposal: Create and promote new "Quick-start guide" pages proposal, we need to create a new repository where the "Official Docs" (guides) will live.

Proposed resolution

Create a new repository with required content, scripts, etc.

Tentative Requirements

  • Must be publicly accessible
  • Must contain source documentation, used for later compilation into HTML
  • Source documentation should be in ??ASCIIDocs or RST format??
  • Must include a CI script that will compile source docs into HTML
    • master branch should not contain compiled HTML
    • Upon PR, CI script should compile docs
    • Upon Merge, CI script should compile docs and commit to master-build branch
    • Compiled HTML must be parsable by Drupal.org
  • Must include contribution instructions

These requirements are incomplete and need review.

Remaining tasks

  • Collaboratively review and revise requirements. Particularly:
    • Determine ASCIIDocs vs RST question
    • Determine HTML requirements for Drupal.org parsing
  • Create proof of concept (POC) branch for RST based docs See https://gitlab.com/grasmash/drupal-docs
  • Create POC for ASCIIDocs based docs. @jhodgdon?
  • Create CI scripts

Comments

grasmash created an issue. See original summary.

grasmash’s picture

grasmash commented
Issue summary: View changes

Some initial thoughts on the first of the tasks, "Determine ASCIIDocs vs RST question."

I initially assumed we'd simply go with ASCIIDocs given that the Drupal 8 User Guide already uses it. However, I found that the learning curve was steeper for ASCIIDocs as compared to RST, and I had difficulty attempting to "Create POC for ASCIIDocs based docs." I quickly spun up a RST based POC. I thought it would be worth raising this for discussion.

A quick pro/con comparison:

RST

Pros
  • Requires only PHP dependencies for docs compilation & uses same tools already used by Drupal community. E.g., Composer. Lowers the bar for setting up local environment for contribution.
  • Parser is PHP based. Lowers bar for contributing upstream to the parser itself, and for contributing to bespoke Drupal.org parser customizations.
  • Used by other popular PHP frameworks. Doctrine, Symfony, etc.
Cons
  • Choosing RST would result in RST being used for all "Official Guides" except Drupal 8 User Guide, which would remain in ASCIIDocs format. This is a bad user experience.

ASCIIDocs

Pros
  • Already used by the Drupal 8 User Guide.
  • Very powerful and feature-rich tool.
Cons
  • Requires installing non-PHP tools. E.g., asciidoc (python based) and xmlto.
  • Requires usage of unfamiliar .xsl and .conf files for ASCIIDocs configuration.

My gut is telling me to stick with ASCIIDoc despite the many pros of RST. In the end, I think I may just need to rely on @jhodgdon to assist with the repo configuration. Anyway, it's open for discussion!

grasmash’s picture

grasmash commented
Issue summary: View changes
grasmash’s picture

grasmash commented
Issue summary: View changes
grasmash’s picture

grasmash commented
Issue summary: View changes
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

I'm confused about this issue:
a) It doesn't seem to have a relationship to what I think should be the parent issue
b) I already volunteered to set up the AsciiDoc and repo for the quick start guides
c) I think we want to stick with AsciiDoc, since we already have a toolchain for getting it into PDF, other ebooks, and drupal.org.

So I think we should close this as Duplicate. When we're ready on the parent issue to open the repo, comment there and I will be happy to set it up.

grasmash’s picture

grasmash commented

Updating issue to reflect Slack convo with @jhodgdon:

a) It doesn't seem to have a relationship to what I think should be the parent issue

The other issue was the general plan for a “quick start guide,” this is a smaller scope issue that is specifically for the task of creating the repo.

b) I already volunteered to set up the AsciiDoc and repo for the quick start guides

Great! This issue is for you then :)

c) I think we want to stick with AsciiDoc, since we already have a toolchain for getting it into PDF, other ebooks, and drupal.org.

That seems like a strong argument. Would you mind creating a new branch on the GitLab repo with the ASCIIDocs set up?

Some further points discussed on Slack:

Is it going to be translated? the structure of the repo depends on that question. and the scripts.

It seems like we would need to adopt a translated structure so as not to preclude support on non-english languages in the future.

Let me know if there are any other outstanding questions to address. Thank you!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

I thought we were going to manage this via a drupal.org repo? I am not aware of any other official drupal projects using Gitlab. Some are on Github. The argument for using Github instead of drupal.org is generally "lots of people have accounts there and know how to use it". Gitlab though... not so much?

Also, the usual practice when spinning off an issue to start work on something that has been planned, would be to post a comment on the parent issue that points people to your child issue, so they know about it, and to at least mark them as "related" or parent/child.

grasmash’s picture

grasmash commented

I thought we were going to manage this via a drupal.org repo?

Yes, I'm intending to use gitlab.com:grasmash/drupal-docs.git and git.drupal.org:project/documentation.git as remotes of the same repo. We can start with the 8.x branch of git.drupal.org:project/documentation.git since that is your preference.

The argument for using Github instead of drupal.org is generally "lots of people have accounts there and know how to use it". Gitlab though... not so much?

Drupal.org is moving to GitLab. According to their most recent update, Drupal.org is more than 80% complete with the required migration work. I chose GitLab for that reason.

Also, the usual practice when spinning off an issue to start work on something that has been planned, would be to post a comment on the parent issue that points people to your child issue, so they know about it, and to at least mark them as "related" or parent/child.

Done and done.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Thanks for linking the issues.

As far as I know, drupal.org would be adopting the gitlab software, on a *.drupal.org server, not using gitlab.com itself, I think?

Anyway, I don't have a gitlab account...

Did we actually decide on the other issue to use the existing documentation repository? I recommended against it, due to the overwhelming volume of issues that that repo has (related to the existing online docs, not the new project), plus some peculiarities it has in the drupal.org nav, as well as not having versions in the issues currently (I don't know why, actually).

grasmash’s picture

grasmash commented

Did we actually decide on the other issue to use the existing documentation repository? I recommended against it

What would you recommend doing instead?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

My recommendation would be to start with a clean, new project and repository. The existing Documentation project has:
- A bunch of unrelated files in the repo that (at least in the pre-8.x branches) should definitely not be deleted.
- A bunch of unrelated issues (it has been the place for issues related to the Community Documentation area on drupal.org).
- Some customizations in the drupalorg project that change its navigation.
- Currently no versions on issues (not sure why or how).

I would strongly suggest starting with a new repo for those reasons.

grasmash’s picture

grasmash commented

My recommendation would be to start with a clean, new project and repository.

Ok, let's do that.

wturrell’s picture

wturrell commented

I get a 404 (i.e. missing or private) for https://gitlab.com/grasmash/drupal-docs - ignore me if that's intentional.

amber himes matz’s picture

amber himes matz
she/her
Primary language English
Location Portland, OR USA
commented

Is there a blocker to or remaining concerns about creating a clean new repo?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

I am not sure... It doesn't seem to me as though the plans are very set for this project, as there has been little activity on the parent issue and I am not aware of it reaching consensus to proceed.

If there is consensus and a plan, then I think it should be put on the parent issue before we go to the trouble of making a repository, because how would we set up a repo/project unless we kind of know the following:
- Who will manage the project? That person should create the Drupal project (so they are the owner), and then others can be designated with issue/committer access.
- Using AsciiDoc? If not, what formatting language, and how will it get built and onto drupal.org? (We know how to take AsciiDoc and build PDFs, other e-books, and get the output onto drupal.org. Using a different formatting process would not be so straightforward.)
- Are there templates for the Guides?
- If we're using the same AsciiDoc toolchain as the User Guide, the "official docs" guides in this project will all be part of a single Documentation Guide (book) on drupal.org. Is that going to be OK?
- Do you want to have a separate contributor guide for this project, or do you want to use the one for the User Guide (which is at https://www.drupal.org/docs/user_guide_guidelines/index.html and it can be amended to include these guides in its scope if the changes are small)?
- What's the planned branch structure for the repo -- same as for User Guide (where we have, for example, 8.x-6.x corresponding to Drupal Core 8.6.x)?
- If the plan is still to mirror this repo on Github, how will that be managed?

I haven't seen answers to these questions yet -- the parent issue seems to be stalled in the "decide on the plans" stage, and this issue still seems premature to me. Or maybe the plans have been decided but the parent issue hasn't been updated? I have no idea what is happening outside of these two issues...

grasmash’s picture

grasmash commented

The parent issue is not stalled. We have adequate agreement to proceed. I'd be happy to answer your questions:

- Who will manage the project? That person should create the Drupal project (so they are the owner), and then others can be designated with issue/committer access.

Me.

- Using AsciiDoc? If not, what formatting language, and how will it get built and onto drupal.org? (We know how to take AsciiDoc and build PDFs, other e-books, and get the output onto drupal.org. Using a different formatting process would not be so straightforward.)

Yes, AsciiDoc. It has precedent and has already been implemented on d.o., which is a strong argument.

- Are there templates for the Guides?

No, we will create them in the repo once it exists.

- If we're using the same AsciiDoc toolchain as the User Guide, the "official docs" guides in this project will all be part of a single Documentation Guide (book) on drupal.org. Is that going to be OK?

That sounds good to me, but I'm a little unclear on how that happens. How is it possible to have separate repos for the User Guide and one for the One Pager guides and still have them compile into a single doc? What command is run, by whom, and where?

- Do you want to have a separate contributor guide for this project, or do you want to use the one for the User Guide (which is at https://www.drupal.org/docs/user_guide_guidelines/index.html and it can be amended to include these guides in its scope if the changes are small)?

I think separate.

- What's the planned branch structure for the repo -- same as for User Guide (where we have, for example, 8.x-6.x corresponding to Drupal Core 8.6.x)?

Yes.

- If the plan is still to mirror this repo on Github, how will that be managed?

The plan is to mirror on GitLab using their automated push feature, as described here: https://docs.gitlab.com/ee/workflow/repository_mirroring.html

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

OK, great! Then the next step is to create a project on drupal.org. Make it a "module" project, even though it isn't a module. As @grasmash will be the project manager, he should create the project.

Then if you add me as a maintainer with Git access, I can create a skeleton with the build scripts, including a contributor guide.

Regarding your question about the builds... Here is what happens:
- AsciiDoc has a concept of a "book". For the User Guide, we have one book for the contributor guide, and one for each language for the User Guide itself.
- Using our customized AsciiDoc/DocBook build scripts, we can take the AsciiDoc source of each book, and use it to build ebooks (PDF, ePub, etc.), as well as HTML-formatted output.
- We have a Drupal module (which I maintain) that can do two things with HTML-formatted output: (a) display it directly in Drupal (reading the HTML files in each time a page is requested, unless the cache kicks in) or (b) import it into Drupal nodes using the Feeds module. It also facilitates editing the AsciiDoc source in a visual editor (you'd still need to export the text file and/or make a patch after editing). Project: https://www.drupal.org/project/asciidoc_display -- and the build scripts will build HTML output suitable for each (separately).
- On drupal.org, we're using that Feeds-based module. So we have a Jenkins job that, whenever we designate, will run the AsciiDoc build scripts for feeds-HTML and read this into drupal.org using Feeds, updating the User Guide and the Contributor Guide. We have the feeds configured so that the Contributor Guide comes in as one Documentation Guide (with each chapter as a child Guide, and individual topics as Documentation Pages), and the User Guide comes in as one Documentation Guide (same structure, but additionally, the other languages are imported as translations of the English version).
- We also have some blocks that appear on User Guide pages that let logged-in users get to the AsciiDoc source, link to the project the pages come from, etc.

So, this project will be set up the same way presumably. It will have a Contributor Guide that will come in as a Documentation Guide, and then presumably another Documentation Guide that will have child pages that are the individual quick-start guides that this project anticipates creating.

And somewhere down the line, if we want to have this type of documentation use a different content type (for "official" guides that are maintained in Git repos), we can easily change the Feeds import. However, that may not be necessary, as there is already a field on these content items (the documentation guides/pages) that marks them as being from AsciiDoc source, so if there needs to be some styling or grouping of "official" as opposed to "community" documentation, we can definitely identify the guides/pages that come from AsciiDoc vs. ones that don't.

Hope that makes sense... Anyway, post something here when you've got the Drupal.org project created and I'll do the next step.

grasmash’s picture

grasmash commented

Thanks so much @jhodgdon! That information is very helpful.

I'm going to be out for the next week, but in the interest of unblocking work, I've quickly created to following project:

https://www.drupal.org/project/official_docs

You've been granted access to edit the project and push to VCS. Let me know if you require any additional permissions.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Active » Fixed

Sorry, this feel off my radar and I was also out of town a bit...

I have finally created a skeleton project in the Git repo for

https://www.drupal.org/project/official_docs

It has two components:
- guidelines -- a Guidelines doc, which is basically the same as the User Guide guidelines doc, except I edited out the parts about the "guiding scenario", and I also removed the concept template. You'll want to edit this. Note that there is some text substitution going on in the build project -- the text that is substituted is in the scripts/guidelines.conf file, so you may also want to edit that.

- source/en -- the place to put one-page guides. I started it out with a dummy "Installation" topic, which is a copy of the one in the User Guide with the cross-references removed. You'll want to either edit that or remove it, and there are also images in the images directory that you can get rid of if you remove that guide.

I verified that the 3 build scripts run on my computer, and I looked at the PDF output (which looked fine). There are instructions in the main README and the scripts README files about what software you'll need to run the builds.

Let me know if you have questions... for now I would say this issue is taken care of.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.