search

backdrop-ops / docs.backdropcms.org

Website for displaying Backdrop CMS documentation and API source code.
https://docs.backdropcms.org/
6 stars 6 forks source link

[META] Write documentation #3

Open jenlampton opened 9 years ago

jenlampton commented 9 years ago

In addition to change records, the API site will hold content for documentation on specific areas of Backdrop. There's a rough equivalent to this on api.drupal.org that uses organic groups.

For Backdrop's API site we can probably get away with a simple Documentation content type with a body field (and perhaps taxonomy for the major version of Backdrop).

jenlampton commented 9 years ago

Related conversation: https://github.com/backdrop-ops/backdropcms.org/issues/26

jenlampton commented 9 years ago

I just created a book here called Developer Documentation (https://api.backdropcms.org/documentation) and would love some help fleshing out these first few pages. We can copy similar pages off drupal.org and change content where necessary.

@docwilmot let me know if you are interested in taking any of this on. I gave your account on the API site access, just in case :)

ghost commented 9 years ago

I'd like to recommend a few changes:

docwilmot commented 9 years ago

Create a new link 'Standards' (or similar) and make 'PHP Coding Standards', 'CSS Coding Standards', 'JavaScript Coding Standards' & 'Code Documentation Standards' sub-links of it. The new 'Standards' link should also probably be made a sub-link of 'Developer Documentation'.

Good plan

This'll greatly help readability and comprehension.

Agreed. But I have issues with having too much depth in navigating docs, like Drupals docs do. So perhaps before we start chopping up, I hoped to come up with a 'table of contents' of the topics that should be in documetnation - priority topics first - and share that. Any suggestions as to what these priorities should be? I also planned to try and understand Layout a bit more before I wrote it, and havent gotten there yet. Will also need sections on converting themes/modules/layouts from D7 to backdrop.

jenlampton commented 9 years ago

I also agree that there are too many pages in Drupal's docs, and would love to see a proposed outline before we do too much dividing. I'd also prefer fewer pages that people can scan or search to find what they need, rather than lots and lots of little pages.

docwilmot commented 9 years ago

Here's a stab at a minimal outline for developer docs. (need to consider user help pages separately on backdropcms.org)

cellear commented 9 years ago

On behalf of outsiders, I think we should have an easy-to-find spot that explains how our particular ecosystem understands the different roles and tasks involved in constructing web software. I'm always astonished at how Balkanized the web development world is - terms like "developer" and "user" mean different things to different communities. (For example, I recently heard on a podcast somebody opine that they couldn't imagine somebody calling themselves a web developer that hadn't mastered at least 2 toolchains. I've been building websites professionally for 20 years, and prior to a few months ago I had never even heard the word "toolchain.")

The document I have in mind is very different from a glossary; it's more akin to an introduction or preface. I'm willing to take a stab at it, if it sounds useful to anybody besides me!

docwilmot commented 9 years ago

Incidentally, the glossary is already done https://api.backdropcms.org/glossary Feel free to suggest additions of course.

docwilmot commented 9 years ago

And I've been building websites amateurly for 12 years and never heard about toolchains till about 2 minutes ago. :)

jenlampton commented 9 years ago

@docwilmot wow, this outline is fantastic :)

How would you feel about separating "building new things" from "converting things"?

For the short term, people will want to be able to get at all the "converting things" documentation in one place, without having to wade through all the other pages. In the long term, this section will also become less and less important, as we gain more Backdrop users who don't come from Drupal, and as there are fewer and fewer sites still running Drupal 7.

Something roughly like this:

I'm not sure the converting section needs to go at the top, or if change records should be inside or outside of it, but something more along these lines.

docwilmot commented 9 years ago

How would you feel about separating "building new things" from "converting things"?

Makes a lot of sense. Were having a chat about the Form API pages just now. Views, FormAPI have had their own API pages in the past, but I'm not sure how those are built. How do we include the API docs like those? Should we keep standalone API repos and link to those or just paste all that into a node or something else?

quicksketch commented 9 years ago

These outlines look great! I like @jenlampton's suggestion of separating out the upgrading docs as well. That will allow for us to do the same thing as needed for Backdrop 1 to Backdrop 2 docs.

jenlampton commented 9 years ago

@docwilmot I think webchick wrote all the Form API docs in a HTML editor and pasted that into a node for the drupal docs, it would be nice if we could do something similar in style (but perhaps easier to maintain?) If you think a separate git repo is the way to go we can certainly do that. We could do something fancy with a custom callback generating a page that's pulled from a repo...

For the Views API I think all the code docs should already be merged into the API site automatically, we'll need to take a look at what (if anything) is still relevant (were all the docs updated to views 3? I thought not...) and see how to incorporate those.

I'm open to suggestions.

quicksketch commented 9 years ago

I think webchick wrote all the Form API docs in a HTML editor and pasted that into a node for the drupal docs, it would be nice if we could do something similar in style

We got the Form API page up in https://github.com/backdrop-ops/api.backdropcms.org/issues/6.

jenlampton commented 9 years ago

Is it on github?

edit: I just read the whole other issue. Looks like it was moved out of github (our api repo - I agree that was the wrong place for it) and into a node. I guess that's okay if we are only talking about dealing with one page. If it starts looking like we have a lot of pages like this one, it might be a good idea to start a new git repo that's pulled in automatically, just so we don't end up going bonkers trying to update or maintain that page in a node, using bueditor ;)

cellear commented 9 years ago

Isn't there a way to store content in a repo? This is my pet issue, my single biggest complaint with Drupal. If there's an easy "Drupal-style" way to do it, let's do it that way. If not, I'll write it for Backdrop. I desperately want it! (@jenlampton, I think you may have referenced "update hooks" as a way to do this, but I wasn't familiar with that technique.)

quicksketch commented 9 years ago

@cellear Are you suggesting that we'd have nodes (or some other data type) stored in Git? I don't think there's any such thing, because it would largely invalidate a huge number of Backdrop/Drupal concepts. Storing content in Git is directly at odds with database-driven content, making things like Views and Fields all but impossible. The only approach that would sort-of work would be replicating data from the Git repository into the database (as nodes or other data), but then you'd end up with a difficult situation how to reconcile the Drupal editing interface with the Git repository, or when something is updated in Git, you'd have to update the node.

All of this could be done, but it'd be significantly more complicated than I think we'd be interested in supporting.

larsdesigns commented 9 years ago

@cellear Have a look at Gollum: https://github.com/gollum/gollum

cellear commented 9 years ago

Are you suggesting that we'd have nodes (or some other data type) stored in Git?

@quicksketch: Yes, that's what I was hoping for :) I'm envisioning something like the way Features works in Drupal. It would pull data from "code" and create content - nodes, terms, users, etc. Once in the DB, this data would be fully managed the way we expect content to be. Perhaps it could be reverted to the disk image, as Features allows, but if it can't it's not a deal-breaker - a one-time load gets me 80% of what I would be looking for. (Though I'm sure once I had that I'd come looking for some of that remaining 20%.)

Does Backdrop store things like Views and Content Types in the DB, or are they immediately written to CMI as JSON? In my dreams, I'd love to be able to hit a switch and have Backdrop dump all of its content into a directory full of JSON files, which I could then load into another Backdrop instance. I might try to write that, if it comes to it. It's not impossible, is it?

@larsdesigns: I prefer to do my work in Backdrop, or possibly Drupal. Switching to a whole other platform loses all that great stuff that brought me here in the first place!

cellear commented 9 years ago

I realize these Drupal projects have wrestled with this problem area, with varying degrees of success:

Among others. Not sure which of these hew closest to Backdrop's philosophy. All of them seem inferior to the import/export capabilities that come with Wordpress, but I haven't used those enough to know if whether they actually live up to their promise.

quicksketch commented 9 years ago

Does Backdrop store things like Views and Content Types in the DB, or are they immediately written to CMI as JSON? In my dreams, I'd love to be able to hit a switch and have Backdrop dump all of its content into a directory full of JSON files, which I could then load into another Backdrop instance. I might try to write that, if it comes to it. It's not impossible, is it?

Backdrop stores all configuration directly as JSON files, with no database involved at all. Backdrop can already do full site export/imports to move everything (Views, Content Types, Fields, etc.) all at once from one site to another. There are limits though: we don't handle enabling/disabling modules or deletion of most things if they contain data (e.g. a field that has content in the database). The validation will stop you. But for 90% situations, everything already works this way. It is pretty much the #1 feature of Backdrop after all. :wink:

That said, I think @larsdesigns has a good suggestion looking into gollum. Backdrop and Drupal both are database-driven, and even though configuration is stored in CMI now, content is still in the database and it's going to be an uphill battle making content store in a file structure so it could be in Git.

docwilmot commented 9 years ago

I must confess I dont get the 'store content in a repo' discussion, not quite sure what you guys are talking about, gollum, etc etc. But I was waiting for this to resolve to move on. Can we get a word on what next? Move on with putting things in Book module or wait?

quicksketch commented 9 years ago

My suggestion for "looking into gollum" was intended for @cellear. For now I'm pretty sure our only good option is to proceed with Book module. We were actually using Github pages for the handbook early on and that turned into a mess pretty quickly. There may be a Backdrop-based file solution at some point, but an adequate file-based solution for Drupal, I don't think we're likely to see one either. The two concepts of file-based management and database-stored management are opposed to each other.

@docwilmot if you need any help or permissions to start implementing the proposed outline, let @jenlampton or I know. I think the outline looks great and already the API site is shaping up nicely. If we do come up with a new mechanism later, we'll still need to have the content; so let's not hold up content on architecture.

docwilmot commented 9 years ago

Thanks. One advantage of having docs in a repository I suspect would probably be versioning. It would be great if we could think up some way of versioning developer docs as well, but based on core. Just as the API docs have paths showing the core version (api.backdropcms.org/api/backdrop/.../1), would be good to have the same apply for docs too (api.backdropcms.org/creating-layouts/1).

jenlampton commented 9 years ago

Git is completely the wrong tool for versioning text -- code yes, english, no. @cellear have you ever tried it? I tried to work on one of my Backdrop articles in Drupal watchdog that way - bad idea.

If we need text versioning for our docs we could use revisions like d.o does.

docwilmot commented 9 years ago

I am going to put fiddling and porting modules aside for now and work on getting this and this done.

@jenlampton could you move your suggested outline to the first post and make it a checklist please?

I'm creating a folder of Google docs here. That link gives edit permission as well.

Will need to be able to check them off as we go.

Thanks.

jenlampton commented 9 years ago

@docwilmot I added a checklist in the main issue, sorry for the delay on that!

serundeputy commented 7 years ago

I checked a bunch of stuff of the list in the OP. Looks great! Everyone has been working hard look how far we've come!