Feedback please - what should the new documentation platform be called?

[Jonathan Hung]

Good question Colin.
Yes, the basic workflow is Fork-clone-edit.

Here's the process currently:

1. Fork then clone the docs-template repository. Run npm install to get the
dependencies.
2. Do your edits to the clone.
3. Add a new remote for your new site / repository (or rename the existing
origin and add a new origin)
4. Push your changes to your new repo.

If updates are made to docs-template while you're working on the clone, you
can get the updates using git.

This would mean you get all the revision history of docs-template mixed in
with your work. Which is not unexpected when working in this way.

If you prefer not to get all the file history, you'd just download a zip
copy of docs-template from github, but this makes getting updates more
difficult.

In the future we would like to investigate Docpad's skeleton function which
may make setting up the initial environment a bit easier. In this case, I'm
not sure how updates are retrieved. We'd have to look into this some more.

Does this workflow make sense? There is room for changes and improvement in
the future - we'll have to be sure to file jiras so we won't forget.

Thanks for your input on the naming.

- Jon.


On Wed, Jul 22, 2015 at 3:40 PM, Colin Clark <colinbdclark at gmail.com> wrote:

> Hi Jonathan,
>
> I think docs-core and docs-template seem like reasonable names. I have one
> question, though, about how the docs-template will be used in practice.
>
> So, let's say I'm going to use this new reusable Fluidic DocPad
> infrastructure to create a new documentation site, say for Flocking. You
> mentioned that I should clone the docs-template repository, and then start
> customizing it for my site. And then I should "push the changes to a new
> repository."
>
> What's the typical workflow for taking a git repository, making changes to
> it, and then committing it all to another repository entirely?
> Fork-clone-edit? Or something else? Would a user of the docs-template repo
> want all your history mixed in with theirs? Walk me through the scenario a
> bit so I understand it fully.
>
> Thanks,
>
> Colin
>
>
> On Jul 20, 2015, at 1:14 PM, Jonathan Hung <jhung at ocadu.ca> wrote:
>
> I'm afraid that "docs-base" could be mis-interpreted as "something to
> build on top of" which isn't the case.
>
> How about: "docs-template" and "docs-core"?
>
>
> On Thu, Jul 16, 2015 at 3:32 PM, Cheetham, Anastasia <acheetham at ocadu.ca>
> wrote:
>
>>
>> On Jul 16, 2015, at 11:28 AM, Jonathan Hung <jhung at ocadu.ca> wrote:
>>
>> Looking at the words I'm using to describe these repositories, maybe:
>>
>>    - "documentation-skeleton" and "documentation-helpers"
>>    - "fluid-documentation-core" and "fluid-documentation-helpers" (fluid
>>    being the maintainers of the project)
>>
>> Here are my impressions; take them for what they’re worth :-)
>>
>> I’m not liking the “fluid-“ prefix; the repositories will be part of
>> fluid-project, which is probably sufficient. We don’t have the prefix on
>> any other repositories…
>>
>> I also find “documentation-“ a bit long. Could we go with “docs-“ ?
>>
>>
>>
>> “skeleton" seems ok (especially if this is similar to something that
>> docpad calls skeleton); another word that comes to mind is “template”
>>
>> “helpers” sounds a bit flouncy to me. It could the perceived to be
>> optional. “base” sounds more required, more foundational.
>>
>> --
>> Anastasia Cheetham – acheetham at ocadu.ca
>> Inclusive Design Research Centre
>> Inclusive Design Institute
>> OCAD University
>>
>>
>
>
> --
>
> *JONATHAN HUNG*
> INCLUSIVE DESIGNER, IDRC
>
> *T:* 416 977 6000 x3951
> *F:* 416 977 9844
> *E:* jhung at ocadu.ca
>
> *OCAD UNIVERSITY*
> Inclusive Design Research Centre
> 205 Richmond Street W, Toronto, ON, M5V 1V3
>
> www.ocadu.ca
> www.idrc.ocad.ca
> _______________________________________________________
> fluid-work mailing list - fluid-work at lists.idrc.ocadu.ca
> To unsubscribe, change settings or access archives,
> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
>
>
>


-- 

*JONATHAN HUNG*

INCLUSIVE DESIGNER, IDRC



*T:* 416 977 6000 x3951

*F:* 416 977 9844

*E:* jhung at ocadu.ca



*OCAD UNIVERSITY*

Inclusive Design Research Centre

205 Richmond Street W, Toronto, ON, M5V 1V3



www.ocadu.ca

www.idrc.ocad.ca
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20150723/1505d1f7/attachment.html>