I suggest you ...

Let docs be private/public per-section in markdown syntax to avoid copying/pasting from private to public

Maintaining an internal copy of docs, and then copying docs over to the public page as features are released, is a pain and leads to maintaining two copies of some of the doc sections, which gets out of date quickly. Being able to flag sections as private, and have a private users view both public and private sections, would be huge for us.

5 votes
Vote
Sign in
Check!
(thinking…)
Reset
or sign in with
  • facebook
  • google
    Password icon
    I agree to the terms of service
    Signed in as (Sign out)
    You have left! (?) (thinking…)
    Matt BornskiMatt Bornski shared this idea  ·   ·  Admin →

    3 comments

    Sign in
    Check!
    (thinking…)
    Reset
    or sign in with
    • facebook
    • google
      Password icon
      I agree to the terms of service
      Signed in as (Sign out)
      Submitting...
      • Lukas LinhartAdminLukas Linhart (Admin, apiary.io) commented  · 

        Hi Maxime,

        currently, we are leaning more towards handling what you are writing as a form of lifecycle.

        Therefore, it's not about marking sections as private, but about having devel/prepro/beta/production cycle for the API. This is also related to branching and our github support.

        Would that make sense for you?

        Regards,

        Lukas

      • Maxime CaillarecMaxime Caillarec commented  · 

        Hi there,

        not sure where you stand on this idea. I find the tool highly cool, but the lack of private sections might be a deal breaker for us.

        As for ourselves, this would be in order to obfuscate some parts of the API. Some endpoints are not to be documented, mainly because they are not stable enough. However, they exist and we use them, and therefore would like to create an API for them.

        Kind regards,

      • Lukas LinhartAdminLukas Linhart (Admin, apiary.io) commented  · 

        Hi Matt,

        just to clarify: is this for the purpose of the workflow (dark launches & feature switches) or for the purpose of security (obfuscating some parts of the API)?

        I am asking because of implications for the Apiary's API, exposing the blueprint through github/sharing API etc.

        Thanks,

        Lukas

      Feedback and Knowledge Base