Move docjam contributions to their proper places
Closed this issue · 14 comments
I'd like to keep a permanent "wip" (work in progress) directory with relaxed commit rules. My own PPX document is way too pre-alpha to be considered ready. Maybe we should just move everything to that?
I don't know -- I'd rather have some note at the top saying the page is a work in progress in the proper directory than have a whole bunch of unrelated documents in one directory. I think a topic is more likely to attract other people who can contribute if it's in the place where it's expected to be, and it's linked from the proper places.
Oh, I think it should be linked to from the proper place. I just think it might be nice to have some sort of way of marking "work in progress, changes may happen without notice or discussion..."
- I'm ok with keeping a scratch directory if it encourages people to start contributing stuff they wouldn't otherwise do.
- I think it's a very high priority to move stuff out of the scratch directory not when it's ready, but rather as soon as we think we know where it belongs in the hierarchy. Otherwise the pages will ossify and we'll have links all over the site to documents in the scratch directory. It's perfectly ok to have work-in-progress stuff anywhere on the site. OCamlverse is about flexibility.
- On the other hand, I'm now realizing this is a weakness of this process compared to a real wiki, where there's a flat structure, and where you can rename things at will. Ideally, we should not care where anything is. Perhaps all the thinking about directory hierarchy is just a waste of our mental bandwidth, and we should instead have just one
contentdirectory. - Let's be more careful about the protocol here. Put your name at the top as a contributor who may make changes without notice to that page. I don't want random people bypassing the protocol and modifying your content under you ie. the liberal protocol doesn't generalize.
Directories form a hierarchy. The link structure of the site won't necessarily follow that same structure, since some pages will be linked to from different parts of the site. So the directory structure can't mirror the link structure. That's a small point in favor of a content directory.
@pmetzger, your ppx page is already very useful.
Directories form a hierarchy. The link structure of the site won't necessarily follow that same structure, since some pages will be linked to from different parts of the site.
Exactly, and I think that's what we should encourage. Right now it seems somewhat unnatural to link from, say, /ecosystem to /learning. But that shouldn't be the case... the directory hierarchy forces us to categorize strongly, and to spend precious time doing so. Instead, we want a flexible graph structure.
The best example is this issue itself. There's no need to consider moving from a scratch directory to another directory -- it's just a matter of linking from the right pages. In effect, we're doubling our work by making the link hierarchy match the directory hierarchy.
The down side is that there won't be a clear directory hierarchy to make site organization clear. But that's an acceptable price to pay, I think.
It's not hard to find the page you want to edit just by following links. When I have thought about editing something in Ocamlverse, I have been going that route rather than clicking through the directories. The link organization of the site is simple and clear (and having it be simple and clear will always be a goal, I'm sure).
For source code, one doesn't have the same options: A single flat directory structure means that the only way to find the file you want is to to scan through a long list of names that are not grouped by content relationships. That's why a directory hierarchy can be a good idea for source code, but a flat structure in Ocamlverse doesn't have the same problem.
All, where do you think I should link my PPX tutorial? A new category in Learning under Advanced?
Sounds good to me.
Thanks again for this, @pmetzger .
I think that how to write a PPX is advanced. The ppx concept and basic usage is not advanced; it's something that everyone should learn about after they've gotten started. (It took me a long time to realize that, because there wasn't any good introductory documentation around, and I'm still learning about ppx.) So I think the introductory parts or the page should be easy to find by accident, and newer users might not look in Advanced.
I guess you might consider splitting the "Writing" section of the ppx document into a different file, and then put that under Advanced. Or you don't want to split the document isn't split--I have no opinion about this--it could be both linked to at the top level in learning, as it is now, and listed on an Advanced page. I don't think that's necessarily a bad idea. Anyway, those are my thoughts.
I wonder whether it would be good to add the term "extension points" to some text associated with the link, since one occasionally comes across that term, and it would be nice to come across a document that explained it.
We can use anchors to split up the content, clarifying in the ppx page that the first part is for beginners and the next parts are advanced. We'd link the first part from Beginner and the second from Advanced in the learning page using anchors.
Ah, that makes sense. Great.
I think if we now remove docjam.md we can close this ticket.
Done.