Tweak user docs #1238

damithc · 2020-06-09T15:50:35Z

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [x ] Documentation update

What is the rationale for this request?

A series of improvements to UG docs

What changes did you make? (Give an overview)/ Is there anything you'd like reviewers to focus on?

It is possible to review one commit at a time as each addresses an independent issue.

Alternatively, can review via the Netlify preview of the PR. Some notable changes (refer to individual commit messages for details).

Rephrased and reorganized the UG siteNav. In particular, introduced a new top-level menu item named 'Working with sites' which contains instructions that apply to the entire site. 369a7d6
Added a 'Setting site properties' page and renamed the previous 'Site configuration' page as 'site.json File' cee297c
Moved PlantUML documentation into the components page. Previously it was a stand-alone page under 'authoring contents'. ceaab4f
Added more links into the Showcase page. f892947
Plugins documentation: demoted info about writing plugins to the bottom of the page as using the built-in plugins is more important to readers than writing their own plugins. 00626fa

Proposed commit message: (wrap lines at 72 characters)

As the commits are fairly independent and self-contained, shall we do a rebase-and-merge?

damithc · 2020-06-10T04:34:24Z

@ang-zeyu looks like I need to use the latest master to for this PR for travis to work. How do I use the latest master branch to preview the website (rather than the installed version of MarkBind)?

ang-zeyu · 2020-06-10T10:33:15Z

@ang-zeyu looks like I need to use the latest master to for this PR for travis to work. How do I use the latest master branch to preview the website (rather than the installed version of MarkBind)?

you can clone the repo then cd to it and run npm link. If you want to revert to the release version simply run npm unlink. (might have to do a npm install -g markbind again too)

Reason: extra spaces causes the popover to be rendered as a '-' in the generated page.

As this page is just a 'quick start' guide, it is better to minimize extra information. Let's mention other templates as a tip rather than a separate tab.

Limit pageNav depth to 3 so that it omits some lower level headings that are contained within examples and not actually meant to appear in the pageNav.

As search bars can be considered a 'component', let's cross-list it in the 'Using Components' page as well.

damithc · 2020-06-10T13:49:57Z

you can clone the repo then cd to it and run npm link. If you want to revert to the release version simply run npm unlink. (might have to do a npm install -g markbind again too)

Nice. Didn't realize it was that easy. Thanks @ang-zeyu

damithc · 2020-06-10T14:45:38Z

This PR is ready for review. It passes Travis but the status is not updated here for some reason.
I'll be sending more documentation PRs after this is merged.

ang-zeyu · 2020-06-10T15:05:29Z

This PR is ready for review. It passes Travis but the status is not updated here for some reason.
I'll be sending more documentation PRs after this is merged.

~~Hmm, might have been since it was a draft PR. I just marked this as ready for review, could you try pushing a dummy commit?~~

Edit: Seems to be occuring on another pr as well
I guess its not really an issue since the netlify build is fine

damithc · 2020-06-10T15:16:33Z

Edit: Seems to be occuring on another pr as well
I guess its not really an issue since the netlify build is fine

Yes, let's proceed without it. The 'pass' status can be found here.

damithc · 2020-06-12T03:46:20Z

Travis status is OK now. Let's get move this PR forward as I have a few more docs PRs to do after this is merged.

ang-zeyu · 2020-06-12T10:26:05Z

docs/userGuide/syntax/diagrams.mbdf

@@ -0,0 +1,144 @@
+## Diagrams


Should we move it under plugins instead? (since it is a plugin after all) #1151

I'm thinking of removing the site/page nav from usingComponents as well (in a separate pr), since it dosen't really fit there with the rest of the vue components, and is already repeated under tweaking the page structure

In the UG we should go by what things look like to users, rather than how they are implemented. They should appear under plugins only if users need to manipulate them as plugins. Similarly, components in the UG doesn't mean Vue components but building blocks readers would be inserting into pages.

Repetition is not an issue as MarkBind is specifically designed to handle repetition. The idea is, things should appear in every place the reader can expect to see it. Having said that, a good policy is to make such repeated content as 'embedded panels' in all places it is repeated except in one place so that reader can see it supposedly belongs in one place but has been repeated in other places for readers' convenience.

ah I see, reason being a new user might not realise it is a plugin before visiting the plugins page, and may mistake installing java/graphviz as a requirement markbind.
How about collapsing the one here into a minimized panel, and inserting something similar to Setting Site Properties? (More info about the site.json file can be found in the panel below. -> `You can include plantUml diagrams via the plantUml plugin as well... click the panel below to find out more)

For the site/page nav, we can make it an embed in a separate pr on that note

ah I see, reason being a new user might not realise it is a plugin before visiting the plugins page, and may mistake installing java/graphviz as a requirement markbind.
How about collapsing the one here into a minimized panel, and inserting something similar to Setting Site Properties? (More info about the site.json file can be found in the panel below. -> `You can include plantUml diagrams via the plantUml plugin as well... click the panel below to find out more)

Note that I've removed all mentions of internal plugins from the UG because the user has no need to know about them. As PlantUML plugin is an internal plugin, users don't even know that it is a plugin.

Hence, from the user POV, PlantUML support is a MarkBind feature. If the user wants to use plantUML diagrams, he has to install java etc. and it is a MarkBind requirement.

Related: My initial idea was not to have any plugins as I wanted everything built-in to be one of our differentiating factors. But we ended up with some plugins along the way. Still, I want to minimize the amount of plugins-related stuff users need to deal with.

Ahh ok noted. Also just realised it would only break if you actually use a <puml> tag, otherwise not having graphviz is fine.

ang-zeyu

Looks neat! Just some minor nits and the scope of the usingComponents page above ⬆️

ang-zeyu · 2020-06-12T10:37:22Z

docs/userGuide/usingPlugins.md


-**WARNING:** Plugins are executable programs that can be written by anyone. This means that they might contain malicious code that may damage your computer.
+A plugin is an extension that adds additional features to MarkBind. Some non-essential MarkBind functionality are provided as plugins so that you can enable/disable/configure them as necessary. MarkBind also supports adding external plugins (written by you or other third parties).


functionalities

Yup. Will fix.

ang-zeyu · 2020-06-12T10:40:19Z

docs/userGuide/usingPlugins.md

+Only run plugins from sources that you trust. Do not run the plugin if the source/origin of the plugin cannot be ascertained.
+</tip-box>
+
+Plugins come as `.js` files. To install an external plugin, simply put it in the `_markbind/plugins` folder. To use the plugin, update the `site.json` file the same way you did for built-in plugins:


is there supposed to be content after the :?

No. Will remove.

damithc · 2020-06-12T12:44:42Z

Thanks for the comments @ang-zeyu

As most MarkBind users are not expected to deal with writing or installing plugins, let's push those instructions to the bottom of the page and simplify the instructions for managing built-in plugins.

There are number of pages that deal with site-level tasks some of which wre listed under 'Authoring Contents' (e.g., search). Let's create a new group of pages named 'Working with Sites' for pages containing info about site-level tasks.

When looking for information on how to set site-wide properties, readers are likely to look for it under 'Working with Sites' pages rather than references. Let's add a page 'Setting Site Properties' page under 'Working with Sites' group. Let's also rename the reference page to 'site.json File' so that it sounds more like a reference page. The new page will mostly refer to the 'site.json File' as setting site-wide properties is mostly done via the site.json file.

As the siteNav group heading are now collapsible even if they are linked, that could cause readers to miss out links behind group headings. Let's unlink group headings and add an 'Overview' link instead.

damithc · 2020-06-13T06:39:23Z

@ang-zeyu fixed the two typos and force-pushed. I think we can go ahead and merge without further reviews as this is just a documentation update. If the are problems, I can fix later in separate PRs. Remember to do a rebase-merge.

ang-zeyu · 2020-06-13T06:51:47Z

did you mean create a merge commit? https://markbind.org/devdocs/devGuide/maintainerGuide.html
We've been using it for PRs with multiple logical commits so far, it keeps the master branch clean while preserving the details under your branch

damithc · 2020-06-13T07:17:44Z

did you mean create a merge commit? https://markbind.org/devdocs/devGuide/maintainerGuide.html
We've been using it for PRs with multiple logical commits so far, it keeps the master branch clean while preserving the details under your branch

That approach is suitable when a big task is done in multiple steps. The merge commit represents the big task while individual commits represent steps. This one is not exactly like that because these are not steps but independent fixes. For example, it's hard to write a commit message for the merge commit of this PR unless we add up all the commit messages from individual commits. Rebase merges will be rare because we require PRs to tackle no more than one thing but this will be one of those rare cases.

ang-zeyu · 2020-06-13T08:17:05Z

👍, will update the developer guide with that info as well

damithc · 2020-06-13T08:25:33Z

👍, will update the developer guide with that info as well

I'll be tackling the DG next. Will add it myself.

damithc closed this Jun 10, 2020

damithc reopened this Jun 10, 2020

damithc added 6 commits June 10, 2020 20:53

index.md: remove stray spaces in the popover definition

da7c447

Reason: extra spaces causes the popover to be rendered as a '-' in the generated page.

gettingStarted.md: trim info on other templates

4004a81

As this page is just a 'quick start' guide, it is better to minimize extra information. Let's mention other templates as a tip rather than a separate tab.

showcase.md: Update existing links, add more links

f892947

Move PlantUML documentation into 'Using Components' page

ceaab4f

usingComponents.md: limit pageNav depth

895ba4e

Limit pageNav depth to 3 so that it omits some lower level headings that are contained within examples and not actually meant to appear in the pageNav.

Cross-list search bars in the components page

2119460

As search bars can be considered a 'component', let's cross-list it in the 'Using Components' page as well.

damithc force-pushed the docs-tweak branch from 55db90e to d0d7962 Compare June 10, 2020 14:24

damithc marked this pull request as ready for review June 10, 2020 14:39

damithc closed this Jun 10, 2020

damithc reopened this Jun 10, 2020

damithc closed this Jun 12, 2020

damithc reopened this Jun 12, 2020

ang-zeyu reviewed Jun 12, 2020

View reviewed changes

damithc added 6 commits June 13, 2020 14:19

Tweak documentation for plugins

d701d5f

As most MarkBind users are not expected to deal with writing or installing plugins, let's push those instructions to the bottom of the page and simplify the instructions for managing built-in plugins.

makingTheSiteSearchable.md: Cross-refer Algolia plugin

904b773

UG/siteNav: unlink group headings

e7ce6aa

As the siteNav group heading are now collapsible even if they are linked, that could cause readers to miss out links behind group headings. Let's unlink group headings and add an 'Overview' link instead.

Fix several broken links

b182c6d

damithc force-pushed the docs-tweak branch from d0d7962 to b182c6d Compare June 13, 2020 06:20

ang-zeyu approved these changes Jun 13, 2020

View reviewed changes

ang-zeyu added this to the v2.15.0 milestone Jun 13, 2020

ang-zeyu merged commit 14262d4 into MarkBind:master Jun 13, 2020

acjh mentioned this pull request Jun 14, 2020

Improve README.md and update major version shown in UG #1250

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tweak user docs #1238

Tweak user docs #1238

damithc commented Jun 9, 2020 •

edited

Loading

damithc commented Jun 10, 2020

ang-zeyu commented Jun 10, 2020

damithc commented Jun 10, 2020

damithc commented Jun 10, 2020

ang-zeyu commented Jun 10, 2020 •

edited

Loading

damithc commented Jun 10, 2020

damithc commented Jun 12, 2020

ang-zeyu Jun 12, 2020

damithc Jun 12, 2020

ang-zeyu Jun 12, 2020

ang-zeyu Jun 12, 2020

damithc Jun 12, 2020

ang-zeyu Jun 12, 2020

ang-zeyu left a comment

ang-zeyu Jun 12, 2020

damithc Jun 12, 2020

ang-zeyu Jun 12, 2020

damithc Jun 12, 2020

damithc commented Jun 12, 2020

damithc commented Jun 13, 2020

ang-zeyu commented Jun 13, 2020

damithc commented Jun 13, 2020

ang-zeyu commented Jun 13, 2020

damithc commented Jun 13, 2020


		WARNING: Plugins are executable programs that can be written by anyone. This means that they might contain malicious code that may damage your computer.
		A plugin is an extension that adds additional features to MarkBind. Some non-essential MarkBind functionality are provided as plugins so that you can enable/disable/configure them as necessary. MarkBind also supports adding external plugins (written by you or other third parties).

Tweak user docs #1238

Tweak user docs #1238

Conversation

damithc commented Jun 9, 2020 • edited Loading

damithc commented Jun 10, 2020

ang-zeyu commented Jun 10, 2020

damithc commented Jun 10, 2020

damithc commented Jun 10, 2020

ang-zeyu commented Jun 10, 2020 • edited Loading

damithc commented Jun 10, 2020

damithc commented Jun 12, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ang-zeyu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

damithc commented Jun 12, 2020

damithc commented Jun 13, 2020

ang-zeyu commented Jun 13, 2020

damithc commented Jun 13, 2020

ang-zeyu commented Jun 13, 2020

damithc commented Jun 13, 2020

damithc commented Jun 9, 2020 •

edited

Loading

ang-zeyu commented Jun 10, 2020 •

edited

Loading