search

TiddlyWiki / TiddlyWikiClassic

TiddlyWiki Classic (not to be confused with TiddlyWiki5: https://github.com/Jermolene/TiddlyWiki5)
https://classic.tiddlywiki.com/
492 stars 114 forks source link

Draft Improving Documentation.tid #255

Closed markkerrigan closed 4 years ago

markkerrigan commented 4 years ago

Draft for separate PR

YakovL commented 4 years ago

Ok, I've updated this branch with commits from TiddlyWiki master and updated split.recipe again, so now this branch is ready to be updated and/or merged.

Some notes to discuss that you mentioned in the other PR thread (with my comments):

Some notes from me:

markkerrigan commented 4 years ago

I made some more minor changes, but I'll address the points you bring up.

  • Documentation Style Guide?

This is more of a question of should we have a Documentation Style Guide, like TW5 does? I don't think it should go to the same extent as the one in TW5 (it's eight separate tiddlers and insists since TiddlyWiki is a of British origin, the English documentation must use British spelling) &_&

  • updating split.recipe /and title: "field" in .tid files

These instructions should be listed in a separate section only if a new .tid file is being added or the title is modified.

  • raising an issue instead of a pull request
  • discussing in the Google Group instead of making a pull request

There should be a sentence saying "You can also raise an issue instead of a pull request". We probably don't need another reference to the Google Group here.

Some notes from me:

  • may be included: separating branches, branch naming, many commits - ok for squash merge

We can include a sentence saying, "Generally, limit pull requests address only changes to a single tiddler at a time (and changes to split.recipe if necessary)."

  • to be clarified: is it possible to add, rename, delete .tid files via GH web interface?

This can all be done by clicking the pencil icon when you view a single .tid. For example here is a link to edit the Camino.tid file

retostauss commented 4 years ago

I did read the guideline (content of Improving%20Documentation.tid), is so far understandable - also for me as a git (hub) newbee. Looking forward to try it out.

markkerrigan commented 4 years ago

accidentally closed

markkerrigan commented 4 years ago

@YakovL , do you think we can go ahead and merge this one? Or do you think we should add another note about naming of the PR relative to its content (ie, prepend with "docs:)?

YakovL commented 4 years ago

Hi Mark, sorry for a really long delay, I've set extending and merging this PR my next goal about TW; I'm not sure I'll do this today, because I'm going to add various things to it (at the very least SuggestChangesPlugin, but as far as I remember I thought of some other changes when reviewed it previously), but I'll totally focus on this this week.

markkerrigan commented 4 years ago

ah yes, it would be good to add SuggestChangesPlugin before going too much further.

YakovL commented 4 years ago

Alright, I've reviewed the possible usage scenarios and added the main changes to this branch that I can currently propose. I've also left 4 TW comments starting with /%# that are "todos" for the future edits (for content suggestions: for new users; for seasoned users: a survey should be created). I think, the current state is good enough for merging, but if you review the changes, that will be helpful. I'm going to merge the whole thing this week, if there's no serious objections.

markkerrigan commented 4 years ago

Yes that looks good, splitting up the topic "Improving Documentation" (into just Documentation) and separating the procedure (Improving Documentation via GitHub) makes sense. Also the language in SuggestChangesPlugin has a number of advantages:

My only question is do we want to explicitly state how we don't intend for people to open issues for documentation improvements in "Improving Documentation via GitHub"? Generally speaking I think we've sort of said unofficially not to raise issues for minor things (or perhaps it's not really necessary to specify this at all?) but I think it's fair to open an issue for complex documentation topics.

Overall, yes we can merge and close this PR.

markkerrigan commented 4 years ago

apologies again, I didn't realize you added these merge changes to this PR.

YakovL commented 4 years ago

ok, let's move on

do we want to explicitly state how we don't intend for people to open issues for documentation improvements in "Improving Documentation via GitHub"

I think no, at least not yet. That would be useful if there were many small issues from many contributors, but for now this sounds somewhat excessive.

I'm merging the current state now and will push the changes to the site shortly. I'm leaving the 4 todo comments (in [[Improving documentation via GitHub]] and [[Documentation]]) for the next iterations.